# AI Prompt Editor Source: https://docs.repforce.ai/ai-assistants/ai-prompt-editor Edit and improve your assistant's prompts using AI-powered suggestions through a conversational interface The AI Prompt Editor is an intelligent tool that allows you to edit and improve your AI assistant's prompts using natural language. Instead of manually editing text, you can chat with an AI assistant that understands your requests and suggests intelligent modifications. ## Overview The AI Prompt Editor provides: * **Conversational editing** - Describe changes in plain language * **Smart suggestions** - AI understands context and makes relevant changes * **Review before apply** - Accept or reject each change individually * **Variable management** - Easily manage pre-call and post-call data * **Template library** - Start with proven prompt templates AI Prompt Editor Interface ## Getting Started Navigate to **Assistants** in the sidebar and click on the assistant you want to edit. In the edit form, scroll to the **System Prompt** section and find the **AI Prompt Editor** tab. Click the **Launch AI Prompt Editor** button. A modal window will open with the editor interface. You must save your assistant at least once before you can use the AI Prompt Editor. ## Interface Overview The AI Prompt Editor has three main areas: ### Chat Panel (Left Side) This is where you interact with the AI: * Type your requests in the input box at the bottom * View conversation history above * Use quick suggestion chips for common actions: * **Make it more concise** - Shorten the prompt * **Add more detail** - Expand with specifics * **Improve clarity** - Make instructions clearer * **Add instructions** - Add new behavioral guidelines ### Editor Panel (Right Side) This shows your current prompt with two tabs: * **System Prompt** - The main instructions for your assistant * **Initial Message** - The greeting message when calls start Toggle between **Edit** mode (textarea) and **Preview** mode (formatted view with diff highlights). ### Side Tabs * **Variables** - Manage pre-call data variables * **Post-Call** - Define data to collect after calls ## Using the Chat ### Making Requests Simply describe what you want to change: **You:** "Make the tone more friendly and casual" **AI:** The AI will suggest changes to make greetings warmer, use more conversational language, and soften formal phrases. **You:** "Add information about our return policy - 30 days no questions asked" **AI:** The AI will find the appropriate place in your prompt and add the return policy details. **You:** "Add instructions for handling angry customers" **AI:** The AI will add behavioral guidelines for de-escalation and when to transfer to a human. ### Tips for Better Results * **Be specific** - "Add a 10% discount mention" is better than "add discount info" * **Provide context** - "When asked about pricing, mention..." gives AI better understanding * **One change at a time** - Break complex changes into multiple requests ## Reviewing Changes When the AI suggests changes, they appear in the diff view: * **Green highlighting** - New text being added * **Red highlighting** - Text being removed * **Blue highlighting** - Text being modified ### Accept or Reject Changes Each change has two buttons: * **✓ Accept** - Apply this specific change * **✗ Reject** - Discard this change You can also use bulk actions: * **Accept All** - Apply all pending changes * **Reject All** - Discard all pending changes Always review changes before accepting. The AI makes intelligent suggestions, but you know your business best. Reviewing Changes with Diff View ## Variables Variables allow you to personalize calls with dynamic data. ### Adding Variables 1. Click the **Variables** tab 2. Click **Add Variable** 3. Enter a name (e.g., `customer_name`, `appointment_time`) 4. Set a default value ### Using Variables in Prompts Type variables directly in your prompt using curly braces: `{variable_name}` **Example prompt:** ``` Hello {customer_name}, I'm calling from {company_name} about your appointment on {appointment_date}. ``` ## Post-Call Schema Define structured data you want to collect during or after calls. ### Adding Post-Call Fields 1. Click the **Post-Call** tab 2. Click **Add Field** 3. Configure: * **Name** - Field identifier (e.g., `meeting_scheduled`) * **Type** - `string`, `number`, or `boolean` * **Description** - What this field captures ### Example Fields | Name | Type | Description | | ------------------- | ------- | ------------------------------------ | | `meeting_scheduled` | boolean | Whether a meeting was booked | | `interest_level` | string | Customer's interest: hot, warm, cold | | `callback_time` | string | Preferred callback date/time | | `objection_reason` | string | Main objection if not interested | The AI can suggest post-call fields based on your prompt. Just ask: "What data should I collect from these calls?" Post-Call Fields Configuration ## Templates When you first open the AI Prompt Editor, you can choose to start with a template: * **Continue with existing** - Keep your current prompt * **Start from scratch** - Begin with a blank prompt * **Start with template** - Choose from pre-built templates Templates are organized by use case: * Sales calls * Customer support * Appointment scheduling * Surveys and feedback * Lead qualification Template Selection Screen ## Saving Your Work Click the **Save** button in the top-right to save all changes to your assistant. The editor auto-detects unsaved changes. If you try to close with unsaved work, you'll be prompted to save or discard. ## Best Practices Templates provide proven starting points. Customize rather than starting from zero. Make small changes, test, and refine. Don't overhaul everything at once. The AI is helpful but not perfect. Always review suggestions before accepting. Make test calls after changes to verify the assistant behaves as expected. ## Related Resources * [System Prompts Guide](/ai-assistants/system-prompt) - Deep dive into prompt writing * [Flow Builder](/ai-assistants/flow-builder) - Visual alternative for conversation design * [Testing Your Assistant](/ai-assistants/testing) - How to test your changes # Assistant best practices Source: https://docs.repforce.ai/ai-assistants/assistant-configuration Quick guide to fine-tune mode, transcriber, model, and other settings for the best call experience. > **Last updated:** September 1, 2025 Getting great results often comes down to **picking the right engine settings**. Use this checklist when configuring an assistant: ## 1. Pick a Mode | Mode | Why choose it? | Notes | | --------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | **Dualplex (Beta)** | Fast turn-taking + premium/cloned voices | Recommended default. Pair with **Gemini Flash 2.0/2.5** or **GPT‑5 Realtime**. | | **Speech-to-Speech (Multimodal)** | Fastest turn-taking & most natural flow | Recommended model: **GPT‑5 Realtime**. | | **Pipeline** | Maximum control over voice & long-form replies | Recommended model: **GPT‑5 Mini**. If you select Pipeline, continue to the **Transcriber** step below. | Want to know more about the differences between the modes? Read the Assistant modes guide. Experiment with all three modes: record the same scenario in each and compare response time and caller satisfaction.
## 2. Choose a Transcriber (Pipeline only) | Transcriber | Accuracy | Latency | Best for | | ------------ | -------- | --------------- | -------------------------------------------------------------------------------- | | **Azure** | ⭐⭐⭐⭐ | ⏱️⏱️⏱️ (slower) | When you need the highest transcription fidelity. | | **Gladia** | ⭐⭐⭐ | ⏱️ (faster) | Good all-rounder for most languages. | | **Deepgram** | ⭐⭐⭐ | ⏱️ (faster) | Another solid choice—test which performs better for your language & audio setup. | > **Tip:** Different languages, accents, or background noise can impact each engine differently. Run a quick A/B test and keep the best performer. ## 3. Select an LLM Model | Model | Strengths | Trade-offs | | -------------------------- | ------------------------------------------------- | --------------------------------------------------------- | | **GPT-5 Mini** | Balanced reasoning with low latency | May be slower than realtime models for rapid turn-taking. | | **GPT-5 Realtime** | Designed for ultra-low-latency voice turns | Best for **Speech-to-Speech** and **Dualplex**. | | **GPT-4o** | Strong reasoning and multimodal understanding | Higher latency. | | **Gemini Flash 2.0 / 2.5** | Ultra-fast for voice turns in Dualplex/Multimodal | Excellent for minimizing perceived latency. | If speed is critical, use **GPT‑5 Realtime** (great for **Speech-to-Speech**) or **Gemini Flash 2.0/2.5** (great with **Dualplex**). For richer reasoning, use **GPT-4o** or **GPT-5 Mini** and offset latency by using filler audios. ## 4. Noise Cancellation If callers are on speaker phone or in a quiet environment, keep **noise cancellation ON**. If your call volume is low or some words are "clipped," **turn it OFF** so the transcriber gets the full waveform. If your assistant is not hearing you well, you can try to turn off noise cancellation. ## 5. Conversation Timers | Parameter | Recommended | Why | | ------------------------ | ----------- | ------------------------------------------------------------------ | | **Re-engagement** | `≈ 30 s` | Gives callers enough time to think. Lower values can feel pushy. | | **Max silence duration** | `≈ 60 s` | Prevents premature hang-ups while still ending truly silent calls. | Test different values in real calls—too low can interrupt, too high leaves awkward gaps. ## 6. Initial Message | Mode | How it's used | Best practice | | -------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Pipeline** | Read **exactly** as written (converted by TTS). | Write the greeting verbatim: "Hello, this is Alex from …". | | **Dualplex** | Read **exactly** as written (rendered via ElevenLabs TTS). | Write the greeting verbatim, then select your cloned voice. | | **Speech-to-Speech** | Interpreted as a **prompt** by the model. | Include instructions like "Greet the customer and say …" *or* prepend `say exactly: ` to ensure literal output. | ## 7. Ambient sound Enabled by default, ambient sound is a feature that adds background noise to the assistant's voice. If the assistant is not hearing you well, you can try to turn off ambient sound or turn the volume lower. ## 8. Endpointing sliders **Control when your assistant starts talking** with the endpointing sensitivity slider at the bottom of assistant settings. | Setting | Effect | Use when | | ---------------------- | --------------------------------------------------------- | ------------------------------------------ | | **Lower sensitivity** | Assistant responds **faster** after caller stops speaking | You want snappy, quick-turn conversations | | **Higher sensitivity** | Assistant waits **longer** before responding | Callers give longer, more detailed replies | **Pro tip:** If your assistant cuts off callers mid-sentence, **increase** the sensitivity. If responses feel sluggish, **decrease** it. ## 9. Debug using call transcript If you are having issues with your assistant, you can use the call transcript to debug the issue. 1. Go to the Call history page. 2. Click on the last call you tested 3. The call transcript will be shown including function calls and its parameters. ## 10. Still have questions? If you have any questions, please contact our support team via the chat widget inside the app. Test different settings with real calls—the right balance depends on your conversation flow and caller behavior patterns. *** Need a complete list of every toggle and slider? See the full Assistant settings reference. # Assistant Modes Source: https://docs.repforce.ai/ai-assistants/assistant-modes Understand the three voice generation modes available for your AI assistants and when to use each one. AI assistants on RepForce.ai can speak in **three distinct modes**. Each mode determines how a caller's speech is understood and how the assistant's reply is generated: Choosing the right mode can improve response time, naturalness, and overall call experience. ## 1. Pipeline | | | | ---------------- | ---------------------------------------------------------- | | **Label in UI** | `Pipeline` | | **How it works** | Speech-to-Text → LLM → Text-to-Speech | | **Latency** | \~800 – 1500 ms (depends on language & model) | | **Best for** | Complex reasoning, dynamic prompts, multi-sentence replies | Pipeline mode first transcribes the caller's words into text, runs that text through the language model, then converts the response back to audio. It's a tried-and-true approach that offers maximum flexibility: * Supports **all voices** in the library (including custom-cloned voices). * Handles **long-form answers** or paragraph-style responses well. * Allows the LLM to **inject variables** and reference earlier context cleanly. ### When to choose Pipeline 1. You need rich, multi-sentence answers (e.g. support queries, detailed explanations). 2. The assistant must reason over **structured data** or complex prompts. 3. You prefer absolute control of the spoken voice (clone or brand voice). ## 2. Speech-to-Speech (Multimodal) | | | | ---------------- | ------------------------------------------------------------- | | **Label in UI** | `Speech-to-speech` | | **How it works** | Direct **speech-to-speech** generation (no intermediate text) | | **Latency** | \~300 – 600 ms (ultra low) | | **Best for** | Natural back-and-forth, short & reactive replies | Speech-to-speech mode skips separate transcription and TTS. Instead, it uses a **multimodal model** that listens and speaks directly, producing more conversational flow: * **Fast turn-taking** – callers experience near-instant responses. * Generates **more expressive prosody** natively (intonation, fillers). * Currently supports a **limited voice set**, but more are added regularly. ### When to choose Speech-to-Speech 1. The conversation needs to feel **snappy** (sales, booking confirmations). 2. Your replies are generally **short sentences** or quick acknowledgements. 3. You're okay with the system-provided voice options for faster interaction. Speech-to-speech is evolving rapidly. If you need a custom cloned voice with low latency, try **Dualplex**. ## 3. Dualplex (Beta) | | | | ---------------- | ------------------------------------------------------------------ | | **Label in UI** | `Dualplex` | | **How it works** | Multimodal STT + LLM (speech-to-speech) with ElevenLabs TTS output | | **Latency** | Low (varies by voice and model) | | **Best for** | Fast, natural replies with high-quality/brand voices (cloned) | Dualplex blends the responsiveness of speech-to-speech with the premium voices and cloning from ElevenLabs used in Pipeline. The assistant uses the multimodal model to understand the caller and plan the reply, then renders the final speech through ElevenLabs for consistent, high‑fidelity output. * **Near-instant turn-taking** similar to speech-to-speech. * Access to **ElevenLabs** voice library, including **custom-cloned voices**. * Great for **short to medium** replies with expressive prosody. * **Recommended default** for most use-cases today; currently in **Beta**. ### When to choose Dualplex 1. You want fast back-and-forth but need a branded or cloned voice. 2. You want more expressive delivery without giving up precise voice choice. 3. You're comfortable using a new feature that is still in Beta. ## Switching modes You can pick the mode for each assistant in **Assistant → Settings → Voice Engine**. Test all three modes to see which delivers the best balance of speed and quality for your use-case. `Dualplex` is currently labeled **Beta**. *** **Pro Tip:** Record two calls – one in each mode – and compare the caller's perceived latency and engagement level to decide which fits your flow. # Cal.com Appointment Scheduling Source: https://docs.repforce.ai/ai-assistants/cal-com-scheduling Enable your AI assistant to schedule appointments using Cal.com Enable your AI assistant to schedule meetings using Cal.com integration. The system automatically configures booking fields for you. ## Setup ### 1. Get API Key 1. Log in to [Cal.com](https://cal.com/) 2. Go to **Settings** → **Developer** → **API Keys** 3. Create a new API key and copy it ### 2. Select Your Region Cal.com offers different API regions. Choose the one that matches your Cal.com account: | Region | API Endpoint | | ---------------- | --------------------------------- | | **US** (default) | `api.cal.com` | | **EU** | `api.cal.eu` | | **Custom** | Your self-hosted Cal.com endpoint | Select your region in the Cal.com configuration panel before connecting. If you're unsure, the US endpoint is the default. ### 3. Connect Cal.com 1. In your assistant settings → **Tools** tab → **Appointment Scheduling** 2. Select **Cal.com** from calendar type 3. Choose your API region 4. Paste your API key 5. Select an event from the dropdown ### 4. Sync Event Click the **"Sync Event"** button to automatically configure booking fields. The sync automatically reads your event type's custom fields and configures them for the AI assistant. Name, email, and phone are set as required. All other custom booking fields are imported automatically. ## Event Types ### Personal Events Select from your personal event types (e.g., 15-minute intro call, 30-minute consultation). ### Team Events You can also book into **team event types**. When your API key has access to team calendars, team events appear in the event dropdown grouped separately from personal events. Team events are useful when you want the AI to book meetings that get distributed across your team members based on their availability. ## Dynamic Booking Fields When you sync an event, the system automatically reads all custom booking fields configured on that event type in Cal.com. This means: * **No manual field configuration** — fields are fetched directly from your Cal.com event type * **Custom fields supported** — any custom fields you add to your Cal.com event type are automatically available * **Auto-refresh on sync** — click "Sync Event" again if you change your Cal.com event's booking fields ## Multiple Calendars Click **"+"** next to Appointment Scheduling to add more calendars (e.g., 15min, 30min meetings). ## Email Setup For calendar invites to work: 1. Define `email` in assistant [input variables](/ai-assistants/settings/prompt-and-tools#call-variables) 2. Pass customer email when creating leads The phone number is automatically included after sync. ## Backward Compatibility If you already have a Cal.com integration configured, your existing settings continue to work without changes. The region defaults to US, and existing field configurations are preserved. You can optionally re-sync to take advantage of dynamic booking fields. ## Troubleshooting **Invalid API Key:** Verify it's active in Cal.com settings and includes `cal_live_` prefix **Sync Failed:** Click **"Troubleshoot"** button to reset fields **No Invites Sent:** Ensure `email` variable is defined and passed with leads **Field Errors:** Use "Troubleshoot" to reset. Only name, email, phone should be required. **Wrong Region:** If you get authentication errors, check that you selected the correct region (EU accounts must use the EU endpoint). For detailed troubleshooting, see [Cal.com Issues](/troubleshooting/cal-com). ## Testing 1. Make a test call and request a meeting 2. Verify booking appears in Cal.com 3. Check calendar invitation email was received # Calendly Appointment Scheduling Source: https://docs.repforce.ai/ai-assistants/calendly-scheduling Enable your AI assistant to schedule appointments using Calendly Enable your AI assistant to schedule meetings using Calendly integration. The AI will check availability and book appointments directly during calls. ## Prerequisites * An active Calendly account * At least one active event type configured in Calendly ## Setup ### 1. Connect Calendly 1. In your assistant settings, go to **Tools** tab → **Appointment Scheduling** 2. Select **Calendly** as the calendar type 3. Click **Connect to Calendly** 4. Authorize the application on the Calendly OAuth page 5. You'll be redirected back to your assistant settings If you have issues connecting, try using an **incognito/private browser window** to resolve authentication conflicts. ### 2. Select Event Type 1. Once connected, click **"Load Events"** to fetch your Calendly event types 2. Select the event type you want the AI to use for bookings 3. Save your assistant ### 3. Configure Location in Calendly Your Calendly event type's location setting must be compatible with the voice agent. 1. Go to [calendly.com](https://calendly.com) → **Event Types** 2. Edit the event type linked to your assistant 3. In the **Location** section, set it to one of: * **"Custom"** — recommended, works in all cases * **"Phone Call" → "Inbound call"** — also works for voice AI If your event type uses only video conferencing (Google Meet, Zoom, Teams), bookings will fail. The voice agent cannot generate meeting links. Either switch to "Custom" or add it as an additional location option. ## Multiple Calendars Click **"+"** next to Appointment Scheduling to add more calendar tools (e.g., different event types for different purposes). Use the "When to schedule" description to help the AI pick the right calendar. ## Organization Accounts If your Calendly account is part of an organization: * **Admin/Owner accounts** can see all event types across team members, including Round Robin and Collective events * **Regular members** can only see their own event types ## Testing 1. Make a test call and request to schedule a meeting 2. Verify the booking appears in your Calendly dashboard 3. Check that the calendar invitation was sent For troubleshooting, see [Calendly Issues](/troubleshooting/calendly). # Custom Mid-Call Tools Source: https://docs.repforce.ai/ai-assistants/custom-tools Learn how to create and configure custom API integrations that your AI assistant can use during calls Custom Mid-Call Tools let your AI assistant interact with external systems during calls. Whether checking inventory, verifying customer data, or fetching real-time information, these tools make your AI more powerful and connected. ## Overview Custom Mid-Call Tools enable your AI assistant to: * Make real-time API calls during conversations * Fetch or submit data to your systems * Make informed decisions based on live data * Provide accurate, up-to-date information to callers - No coding required - just configure the API endpoint and parameters - AI automatically knows when and how to use the tools - Real-time data access during calls - Seamless integration with your existing systems ## Setting Up Your Tool ### 1. Basic Configuration Main Tool Configuration Navigate to **Mid call tools** and click **Create Mid-Call Tool** Fill in the essential details: * **Name**: Use lowercase and underscores (e.g., `check_order_status`) * **Description**: Explain when and how the AI should use this tool * **Endpoint**: Your API URL (e.g., `https://api.yourcompany.com/orders`) * **Timeout**: How long to wait for responses (in seconds) * **Method**: Choose GET, POST, PUT, PATCH, or DELETE Common headers you might need: ```yaml theme={null} Content-Type: application/json Authorization: Bearer your_token ``` ### 2. Variable Configuration Variable Configuration These are the pieces of information your AI will collect during the call: ```yaml theme={null} Name: order_number Type: string Description: "10-digit order number from the customer" ``` Add format requirements in the description: ```yaml theme={null} "Date in dd/mm/yyyy format" "Phone number without spaces" "Email address for confirmation" ``` ## Understanding Parameter Types Text values like names, addresses, or reference numbers ```yaml theme={null} Type: string Examples: "John Doe", "123 Main St" ``` Numeric values like amounts, quantities, or IDs ```yaml theme={null} Type: number Examples: 42, 99.99 ``` Boolean values for yes/no situations ```yaml theme={null} Type: true_false Examples: true, false ``` Add format instructions in descriptions ```yaml theme={null} "Date in dd/mm/yyyy" "Phone without spaces" ``` ## Dynamic Endpoints When using variables in your endpoint URL, make sure to enclose them in curly braces and use the exact parameter name. You can make your endpoints dynamic using variables: ```yaml theme={null} Basic URL: https://api.example.com/orders/status With Variables: https://api.example.com/orders/{order_id}/status ``` The AI will automatically replace `{order_id}` with the actual value collected during the conversation. ## Testing Made Easy Click "Test Tool" to run a test with dummy data: * String parameters: "test" * Number parameters: 1 * Boolean parameters: true You'll see the response code and body, helping you verify everything works. ## Power User Feature: Automation Platform Integration Need more complex logic? Connect your tool to the automation platform for advanced workflows. For advanced integrations and complex workflows, you can combine custom tools with our [Automation Platform](/automation-platform/introduction). Here's how to create powerful integrations: 1. In the automation platform: * Create a new flow * Add a webhook trigger * Build your logic (API calls, data transformation, etc.) * End with "Return Response" 2. In your custom tool: * Use the webhook URL as your endpoint * Add `/sync` at the end * Example: `https://repforce.ai/automation/webhook/abc123/sync` This lets you: * Transform data before/after API calls * Make multiple API calls in sequence * Apply complex business logic * Handle errors gracefully ## Real-World Examples ```yaml theme={null} Name: check_order Endpoint: https://api.yourshop.com/orders/{order_number} Parameters: - Name: order_number Type: string Description: "Order reference (format: ORD-XXXXX)" ``` The AI will: 1. Ask for the order number 2. Fetch the status 3. Explain delivery dates and status to the customer ```yaml theme={null} Name: check_slots Endpoint: https://api.calendar.com/availability Parameters: - Name: service Type: string Description: "Service type (haircut, massage, consultation)" - Name: date Type: string Description: "Preferred date (dd/mm/yyyy)" ``` The AI will: 1. Ask about the desired service 2. Get preferred date 3. Show available time slots ```yaml theme={null} Name: verify_customer Endpoint: https://api.crm.com/verify Parameters: - Name: phone Type: string Description: "10-digit phone number" - Name: email Type: string Description: "Email address for verification" ``` The AI will: 1. Collect contact details 2. Verify against your CRM 3. Proceed based on verification status ## Configuring Your AI The AI needs clear instructions in its system prompt to effectively use your custom tools. Example prompt section: ```yaml theme={null} When to use check_order tool: 1. Customer asks about order status 2. Mentions tracking or delivery 3. Wants to know where their package is How to use it: 1. Ask for order number if not provided 2. Verify format (ORD-XXXXX) 3. Use tool to fetch status 4. Explain results in simple terms ``` Test your tools with various conversation flows to ensure the AI handles all scenarios smoothly. Start with simple test calls before going live. # Filler Audio Source: https://docs.repforce.ai/ai-assistants/filler-audio Learn how to use filler audio to create more natural conversations with your AI assistant Filler audio adds natural conversation sounds (like "hmm" or "one moment") while your AI assistant processes responses. This creates a more human-like interaction by eliminating awkward silences. ## How It Works When enabled, your AI assistant will: * Use short audio fillers during processing time * Maintain engagement while formulating responses * Signal active listening to the caller ## Benefits 1. **Improved Conversation Flow** * Eliminates dead air * Keeps callers engaged * Reduces hang-ups * Creates natural dialogue rhythm 2. **Enhanced User Experience** * More human-like interaction * Less awkward waiting * Better caller retention * Increased trust ## Setup 1. Go to your [AI assistant settings](/ai-assistants/settings/general#audio-enhancement-settings) 2. Find the "Filler Audio" option 3. Toggle it on 4. Save your changes ## Best Practices ### Combine with Fast Engine * Use filler audio with the Fast Engine setting * Creates the most natural conversation flow * Minimizes perceived response time ### Use Cases * **Sales Calls**: Keep prospects engaged * **Customer Service**: Show active listening * **Lead Qualification**: Maintain natural flow ## Testing After enabling filler audio: 1. Make a test call 2. Listen for natural transition sounds 3. Verify timing and appropriateness 4. Adjust if needed *** **Tip:** Start with filler audio enabled - you can always disable it if it doesn't suit your use case. # Flow Builder Source: https://docs.repforce.ai/ai-assistants/flow-builder Design conversation flows visually with an intuitive drag-and-drop interface Flow Builder is a visual, drag-and-drop conversation flow editor that lets you design AI assistant scripts without writing code. Create multi-step conversation flows by connecting nodes that represent different actions and decision points. ## Overview Flow Builder provides: * **Visual design** - Drag-and-drop nodes on a canvas * **Multiple node types** - Messages, prompts, actions, and more * **Branching logic** - Create different paths based on responses * **Settings panel** - Configure agent personality and behavior * **Import/Export** - Save and share flows as JSON files Flow Builder Interface ## When to Use Flow Builder * Structured conversation scripts * Multi-path decision trees * Complex call flows with branches * Visual thinkers who prefer diagrams * Simple, linear conversations * Highly dynamic AI responses * Quick prompt iterations * Text-focused editing ## Getting Started Navigate to **Assistants** and click on the assistant you want to edit. In the edit form, scroll to the **System Prompt** section and click the **Flow Builder** tab. Click **Launch Flow Builder**. A full-screen editor will open. * **Continue with existing** - Edit your current flow * **Start from scratch** - Begin with just a Start node * **Start with template** - Load a pre-built flow template ## Interface Overview ### Canvas Area (Center) The main workspace where you build your flow: * **Nodes** - Drag to reposition * **Connections** - Lines showing flow between nodes * **Grid background** - Helps with alignment * **Zoom controls** - Zoom in/out and fit to view * **Pan** - Click and drag on empty space to move around ### Bottom Toolbar Quick actions for managing your flow: | Button | Action | | -------------- | ---------------------------------- | | ⚡ Auto Layout | Automatically arrange nodes neatly | | 📋 Duplicate | Copy selected node | | 🗑️ Delete | Remove selected node or connection | | **+ Add Node** | Add a new node to the canvas | ### Settings Panel (Right Side) Configure your assistant's personality and behavior: * **Agent Name** - The name your AI will use * **Agent Type** - Sales, Support, Survey, etc. * **Language** - Spoken language for calls * **Assertiveness** - How pushy the AI should be * **Humor** - Level of humor in responses * **Variables** - Pre-call data fields * **Post-Call Fields** - Data to collect after calls ## Node Types Flow Builder has 5 node types, each with a specific purpose: Flow Builder Node Types ### Start Node (Green) The entry point of every conversation. Every flow must have exactly one Start node. **Properties:** * **Greeting** - The initial message when the call begins **Example:** "Hi, this is Sarah from Acme Insurance. How are you today?" ### Speak Node (Blue) Delivers a pre-written message exactly as specified. Use when you need precise wording. **Properties:** * **Text** - The exact message to speak * **Outcomes** - Different paths based on customer response **Example:** "We're offering a limited-time 20% discount on all plans. Would you like to hear more?" ### Prompt Node (Purple) Gives the AI instructions on how to respond. More flexible than Speak nodes - the AI generates contextual responses. **Properties:** * **Prompt** - Instructions for the AI * **Outcomes** - Different paths based on response categories **Example prompt:** "Ask the customer about their current insurance coverage. Be conversational and empathetic. Listen for mentions of their family size, budget concerns, or timeline." ### Action Node (Orange) Executes special actions during the call. **Action Types:** * **Call Forward** - Transfer to another number * **Book Appointment** - Schedule using connected calendar * **Custom Action** - Trigger a custom mid-call tool **Example:** Forward to sales team at +1-555-123-4567 when customer is ready to purchase. ### End Node (Red) Terminates the call or transfers to another destination. **End Types:** * **End Call** - Hang up with a closing message * **Forward Call** - Transfer to a phone number * **Transfer Agent** - Hand off to another assistant **Example closing:** "Thank you for your time today. Have a great day!" ## Working with Nodes ### Adding Nodes 1. Click **+ Add Node** in the bottom toolbar 2. Select the node type from the dropdown 3. The node appears on the canvas 4. Drag it to your desired position ### Connecting Nodes 1. Hover over a node's bottom edge to see the **output handle** (small circle) 2. Click and drag from the output handle 3. Connect to another node's **input handle** (top edge) 4. Release to create the connection ### Editing Nodes 1. Click on any node to select it 2. The node's properties appear in a panel 3. Edit the text, prompt, or settings 4. Changes save automatically to the canvas ### Deleting Nodes * Select a node and press **Delete** key, or * Select a node and click the 🗑️ button in the toolbar The Start node cannot be deleted. Every flow must have one Start node. ## Outcomes (Multiple Paths) Speak and Prompt nodes can have multiple **outcomes** - different paths based on how the customer responds. ### Adding Outcomes 1. Select a Speak or Prompt node 2. In the properties panel, find **Outcomes** 3. Click **Add Outcome** 4. Name the outcome (e.g., "Interested", "Not interested", "Wants callback") ### Connecting Outcomes Each outcome appears as a colored dot at the bottom of the node. Connect each outcome to a different destination node to create branching logic. Conversation Branching with Outcomes **Example flow:** ``` [Start] → [Ask about interest] ↓ [Prompt: "Ask if interested"] ↓ ┌─────────┼─────────┐ ↓ ↓ ↓ [Interested] [Maybe] [Not Interested] ↓ ↓ ↓ [Book Demo] [Send Info] [Thank & End] ``` ## Settings Panel Flow Builder Settings Panel ### Agent Identity | Setting | Description | | -------------- | ------------------------------------------------ | | **Agent Name** | Name the AI uses to introduce itself | | **Agent Type** | Preset personality: Sales, Support, Survey, etc. | | **Language** | Primary language for the conversation | ### Personality | Setting | Options | Description | | ----------------- | ------------------------- | --------------------------- | | **Assertiveness** | Low / Medium / High | How persistent the AI is | | **Humor** | Off / Low / Medium / High | Level of humor in responses | ### Variables Add pre-call data that can be used in your messages: 1. Click **Add Variable** 2. Enter a **Name** (e.g., `product_interest`) 3. Set a **Default Value** Use variables in messages with curly braces: `{variable_name}` **Example:** "Hi , I see you were interested in our ." ### Post-Call Fields Define data to extract from calls: 1. Click **Add Field** 2. Enter **Name**, **Type**, and **Description** 3. The AI will attempt to fill these based on the conversation **Types:** `string`, `number`, `boolean` ## Import/Export ### Export Your Flow 1. Open the Settings panel 2. Scroll to the bottom 3. Click **Export JSON** 4. Save the `.json` file ### Import a Flow 1. Click **Import JSON** in settings 2. Select your `.json` file 3. The flow loads on the canvas Export your flows regularly as backups. You can also share flows with team members this way. ## Voicemail Settings Configure what happens when voicemail is detected: * **Voicemail Message** - Message to leave if voicemail answers * **End Call on Voicemail** - Toggle to automatically hang up on voicemail ## Saving Your Flow Click the **Save** button in the top-right corner to save your flow to the assistant. The flow is stored as JSON in your assistant's system prompt field. If you switch to the Classic Editor, you'll see the raw JSON data. ## Best Practices Begin with a basic flow and add complexity gradually. Test at each step. Prompt nodes give the AI flexibility. Use them for dynamic, context-aware responses. Before building, sketch the main paths: positive, negative, and neutral responses. Make test calls covering all paths. Verify each outcome leads to the right destination. ## Troubleshooting * Ensure you're dragging from an **output handle** (bottom) to an **input handle** (top) * Check that you're not creating a circular connection * The Start node only has an output, End node only has an input * Check your internet connection * Ensure you have at least one node (besides Start) * Look for any validation errors in the settings panel * Use Speak nodes for exact wording requirements * Make Prompt node instructions more specific * Check that outcomes are clearly defined and connected ## Related Resources * [AI Prompt Editor](/ai-assistants/ai-prompt-editor) - Chat-based alternative for prompt editing * [System Prompts Guide](/ai-assistants/system-prompt) - Understanding prompt fundamentals * [Testing Your Assistant](/ai-assistants/testing) - How to test your flows # GoHighLevel Appointment Scheduling Source: https://docs.repforce.ai/ai-assistants/gohighlevel-scheduling Learn how to enable your AI assistant to schedule appointments using GoHighLevel integration Enable your AI assistant to seamlessly schedule meetings and appointments using GoHighLevel integration. This powerful feature allows your AI to check availability and book meetings directly during calls with your existing GoHighLevel calendar system. ## Prerequisites Before setting up GoHighLevel integration, you'll need: * An active GoHighLevel account * Calendar(s) configured in your GoHighLevel location * Admin or appropriate permissions to authorize app connections ## Setup Process ### 1. GoHighLevel Account Requirements **Account Setup:** * Ensure you have an active GoHighLevel account * Verify that your calendars are properly set up in your account * Confirm you have the necessary permissions to connect external applications **Calendar Configuration:** * Create or verify existing calendars in your GoHighLevel location * Set appropriate availability times and booking settings * Configure any required custom fields for appointments ### 2. Connecting GoHighLevel to Your Assistant 1. In your [AI assistant settings](/ai-assistants/settings/prompt-and-tools#default-tools), navigate to the **Tools** section 2. Select **Appointment Scheduling** from the available tools 3. Choose **GoHighLevel** as your calendar integration type 4. Click **Connect to GoHighLevel** **OAuth Authorization Process:** 1. You'll be redirected to GoHighLevel's authorization page 2. **Choose your account** from the available options 3. **Authorize the application** to access your calendar data 4. You'll be redirected back to your assistant settings If you have issues connecting to GoHighLevel, try using an **Incognito/Private browsing window** as this can resolve authentication conflicts. ### 3. Calendar Selection After successful connection: 1. Select the specific **calendar** from your GoHighLevel location 2. Your available calendars will be automatically fetched and displayed 3. Choose the calendar where appointments should be booked ### 4. Testing the Integration **Essential testing steps:** 1. Make a test call to your AI assistant 2. Request to schedule an appointment during the conversation 3. Verify the booking appears in your GoHighLevel calendar 4. Check that confirmation details are sent appropriately 5. Test different scenarios (available/unavailable times) ## Required Information from GoHighLevel To complete the integration, the system needs access to: ### From Your GoHighLevel Account: * **Location ID:** Automatically obtained during OAuth authorization * **Calendar IDs:** Retrieved from your location's available calendars * **Access Tokens:** Managed automatically through OAuth flow ### Calendar Permissions: * **Read calendar availability:** To check open time slots * **Create appointments:** To book new meetings * **Access calendar details:** To retrieve calendar names and settings ## Integration Features ### Automatic Appointment Booking * **Real-time availability checking:** AI verifies open time slots * **Instant booking confirmation:** Appointments created immediately in GoHighLevel * **Conflict prevention:** System prevents double-booking * **Time zone handling:** Respects calendar and customer time zones ### Email Requirement for Appointments **Important:** To book appointments, your AI assistant needs an email address from the customer. **Setup options:** 1. **Define email in input variables:** Add `email` as an input variable in your [assistant settings](/ai-assistants/settings/prompt-and-tools#call-variables) 2. **Import leads with email:** When importing leads, ensure email addresses are included 3. **AI collection during call:** Configure your assistant to ask for email during the conversation if not available **Example prompt instruction:** ``` "If the customer wants to book an appointment and I don't have their email address, ask them to provide their email address for the booking confirmation." ``` ## Best Practices ### Calendar Management * **Keep calendars updated:** Ensure availability is current in GoHighLevel * **Set buffer times:** Configure appropriate gaps between appointments * **Use clear calendar names:** Makes selection easier during setup ### Assistant Configuration * **Include calendar context in system prompt:** Help AI understand booking scenarios * **Define appointment variables:** Extract relevant information for GoHighLevel * **Configure appointment duration:** Specify how long appointments should be **Appointment Duration Setup:** Tell your AI assistant about appointment lengths in the system prompt: ``` "When booking appointments, use 45-minute slots. If a customer says they want to meet at 8:00 AM, set the end_time to 8:45 AM. Always calculate the end_time based on the start time plus 45 minutes." ``` **Example scenarios:** * Customer says: "Can we meet at 2:00 PM?" * AI books: 2:00 PM - 2:45 PM (45-minute slot) * **Test various scenarios:** Different time requests, conflicts, rescheduling ### Security & Compliance * **Token management:** OAuth tokens are refreshed automatically * **Data privacy:** Only necessary calendar data is accessed * **Permission scope:** Integration uses minimal required permissions ## Troubleshooting ### Quick Fixes: **Missing API Key Error:** * **Solution:** Disconnect and reconnect your GoHighLevel account, then select an assistant and save * **Steps:** Go to [assistant settings](/ai-assistants/settings/prompt-and-tools#default-tools) → Appointment Scheduling → Disconnect → Connect again → Select assistant → Save **Connection Issues:** * **Try incognito mode** for OAuth authorization * **Verify account permissions** and calendar setup **Calendar Problems:** * **Refresh connection** if calendars don't appear * **Check time zones** and availability settings For comprehensive GoHighLevel troubleshooting, including detailed solutions and additional issues, see [GoHighLevel Issues](/troubleshooting/gohighlevel). # Initial Message & Audio Source: https://docs.repforce.ai/ai-assistants/initial-message Learn how to create effective initial messages and use custom audio files for the best first impression The first few seconds of a call are crucial - they determine whether the customer stays on the line. You have two options for your assistant's first greeting: text-based initial message or custom initial audio. ## Initial Message This is the first thing your AI assistant says when starting a call. The message is read exactly as written, so: ### Best Practices 1. **Keep it Short** * Aim for 5-10 seconds * Get to the point quickly * Avoid long company introductions 2. **Write Exactly as Needed** * Include proper diacritics (é, ñ, ü, etc.) * Use punctuation for proper pausing * Write numbers as they should be spoken 3. **Example Formats** ``` Good: "Hi! This is Sarah from ABC Company. How can I help you today?" Better with pausing: "Hi! This is Sarah from ABC Company... How can I help you today?" With diacritics: "¡Hola! Soy María de ABC Company. ¿Cómo puedo ayudarte?" ``` ## Initial Audio For the best first impression, you can use a pre-recorded audio file: ### Benefits * Professional quality * Perfect pronunciation * Human warmth * Consistent delivery * Higher customer retention ### Setup Process 1. Record your greeting with a professional voice actor 2. Upload the audio file in [assistant settings](/ai-assistants/settings/general#call-flow-configuration) 3. Clone the same voice for the rest of the conversation 4. Enable initial audio playback ### Best Practices 1. **Recording Quality** * Use professional equipment * Record in a quiet environment * Maintain consistent volume * Save in high quality format 2. **Voice Matching** * Use the same voice actor for cloning * Maintain consistent tone and style * Match energy levels 3. **Content Guidelines** * Keep under 10 seconds * Include company name * State purpose clearly * Sound welcoming ### Example Script Structure ``` [Greeting] + [Company Name] + [Purpose/Question] "Hello! This is ABC Company calling about your recent inquiry. How are you today?" ``` ## Combining Both Methods You can set up both: * Initial audio as primary greeting * Initial message as backup * System will use audio when available ## Testing Before going live: 1. Call your assistant 2. Listen for: * Clear pronunciation * Natural pauses * Proper volume * Smooth transition to AI conversation ## Language Considerations * Each language needs its own initial message/audio * Use native speakers for recordings * Consider regional accents * Test with target audience *** **Pro Tip:** Record several versions of your initial audio and test which one gets better response rates. # General Settings Source: https://docs.repforce.ai/ai-assistants/settings/general Basic configuration settings for your AI assistant including call direction, phone numbers, voice, and advanced settings. Configure the fundamental settings for your AI assistant including call direction, phone numbers, voice selection, and technical parameters. ## Quick Start Guide Ready to set up your first AI assistant? Here's the essential flow: 1. **Choose Call Direction:** Inbound (answers calls) or Outbound (makes calls) 2. **Set Assistant Name:** Internal label like "Support Bot" or "Sales Bot" 3. **Configure Phone Numbers:** Assign platform numbers, SIP, or Caller ID 4. **Select Voice & Language:** Choose from built-in voices or clone custom ones 5. **Adjust Advanced Settings:** Fine-tune models, timing, and audio parameters **Always test your changes** by calling the assistant or running a small campaign to confirm it behaves as expected. Follow this page section by section to configure your assistant. Each setting includes detailed explanations and best practices to help you make the right choices. ## Call Direction & Basic Setup ### Assistant Type Choose whether your assistant handles **inbound** or **outbound** calls. This fundamental choice affects which other options become available. **Inbound (Receive calls):** Handles incoming calls from customers. See [Inbound calls overview](/inbound-calls/overview). **Outbound (Make calls):** Initiates calls to leads or customers. See [Outbound calls overview](/outbound-calls/overview). ### Assistant Name A descriptive name to identify your assistant in the dashboard. Use something memorable that describes the assistant's purpose (e.g. "Sales Qualifier", "Support Bot", "Appointment Scheduler"). ## Phone Number Configuration Your assistant needs a phone number to operate. The available options depend on your call direction choice. ### For Outbound Assistants You can use: * **Platform numbers:** Numbers rented directly from our platform * **SIP numbers:** Connect your existing VOIP/PBX system * **Caller ID only:** Verify ownership of an existing number to display it on outbound calls ### For Inbound Assistants You can use: * **Platform numbers:** Numbers rented directly from our platform * **SIP numbers:** Connect your existing VOIP/PBX system **Note:** Caller ID only numbers cannot handle inbound calls - they only display on outbound calls. ### Pricing & Costs * **Platform numbers:** Monthly rental fees starting from \$3.99/month. See [renting a dedicated number](/pricing/number-rentals#1-renting-a-dedicated-number) for detailed pricing. * **SIP integration:** No monthly fee, only \$0.00045/min for AI bridging. See [SIP integration pricing](/pricing/number-rentals#2-sip-integration-no-monthly-fee). * **Caller ID:** No monthly fee, region-based per-minute rates (e.g., \$0.01/min in the US). See [Caller ID pricing](/pricing/number-rentals#3-caller-id-no-monthly-fee). See [Phone number types](/phone-numbers/types) for detailed explanations and [SIP integration guide](/provisioning/sip-trunking/sip-integration) for VOIP setup. ## Engine Type (Voice Processing Mode) Choose how your AI processes speech and generates responses. Each mode is optimized for different use cases. See [Assistant modes](/ai-assistants/assistant-modes) for detailed comparisons. ### Pipeline Mode Traditional Speech-to-Text → LLM → Text-to-Speech pipeline. Offers maximum control over voice selection and response generation. **Best for:** Complex reasoning, function calling, custom voice requirements ### Speech-to-Speech Mode Direct speech-to-speech generation without intermediate text processing. Provides the most natural conversational flow. **Best for:** Quick conversations, natural back-and-forth dialogue ### Dualplex Mode (Beta) Combines fast multimodal processing with premium ElevenLabs voice output. **Best for:** Most use cases - recommended default ## Language Configuration ### Primary Language The main language your assistant will use for speech recognition and synthesis. This affects: * Speech recognition accuracy * Available voice options * Filler audio phrases * Voice model selection See [Language support](/conversation-design/language-support) for all available languages and accents. ### Secondary Languages Additional languages your assistant can understand and speak. Useful for: * Multilingual customer support * International businesses * Code-switching conversations **Note:** The AI can detect which language the customer is speaking and respond appropriately. ## TTS Provider & Voice Selection ### TTS Provider Select your Text-to-Speech provider. Available in **Pipeline** and **Dualplex** modes. **Available Providers:** * **ElevenLabs** - High-quality voices * **Cartesia** - Fast, low-latency synthesis Your assistant can choose from existing voices, clone custom voices, or request voices from the ElevenLabs library. ### Voice Options You have three ways to get the perfect voice for your assistant: **1. Choose from existing voices:** * **Professional voices:** Pre-trained, high-quality options from ElevenLabs * **Multiple accents:** Available for most languages * **Gender options:** Male and female voices for each language * **Tone variety:** From formal business to casual conversational **2. Clone a custom voice:** Create a custom voice by uploading audio samples. Available in **Pipeline** and **Dualplex** modes. **Requirements by provider:** * **Cartesia** - Single audio file, at least 10 seconds, 1 speaker, no background noise * **ElevenLabs** - Samples over 1 minute, 1 speaker, no background noise. Max 5 minutes total. **Process:** 1. Click "Clone voice" next to voice selector 2. Select provider (Cartesia or ElevenLabs) 3. Choose the voice language 4. Enter a name for your voice 5. Record or upload audio 6. Wait for processing 7. Select your new voice from dropdown **Use cases:** * Brand consistency with company spokesperson * Personal touch for customer relationships * Matching voice to specific business persona **3. Request from ElevenLabs library:** You can request specific voices from the ElevenLabs public library - contact support to add them to your account. Browse the [ElevenLabs Voice Library](https://elevenlabs.io/docs/product-guides/voices/voice-library) to discover thousands of professional voices across different languages, accents, and use cases. See [Voice selection guide](/ai-assistants/voice-selection) for detailed setup instructions. ## Timezone Configuration ### Timezone Set the timezone your assistant operates in. This affects: * Time-based variables in conversations * Appointment scheduling functions * "Current time" references in system prompts * Timestamps in call logs and data extraction **Important:** Choose the timezone where your business operates or where most customers are located. The assistant will use this for any time-related calculations or scheduling. ## Audio Enhancement Settings ### Ambient Sound Optional background sound mixed under your assistant's voice to mask processing delays and create a more natural audio experience. **Options:** * **None:** No background sound (default) * **Office:** Subtle office environment sounds **Volume control:** Adjust the level of ambient sound relative to the voice. Lower values are usually better - too much background sound can interfere with speech recognition. Turn off or lower volume if the assistant isn't hearing the customer clearly. ### Filler Audio Short conversational phrases like "mhm", "okay", "I understand" that play during AI processing time. See [Filler audio guide](/ai-assistants/filler-audio) for full details. * Eliminates awkward silences during processing * Keeps callers engaged * Creates more natural conversation flow * Reduces hang-up rates **Language-aware configuration:** Filler phrases are automatically set for your selected language: "Great!", "Perfect!", "Super!" "Hmm.", "I see.", "Okay." "Right?", "Really?", "How so?" "Okay.", "I understand.", "Got it." **Customization:** You can edit the default phrases for each category to match your brand voice or regional preferences. Enable by default - most conversations benefit from fillers. Test with your target audience and adjust phrases to match your assistant's personality. ## Advanced Settings ### LLM Model Selection Choose the best language model for your assistant's mode. See [LLM model selection guide](/ai-assistants/assistant-configuration#3-select-an-llm-model) for detailed recommendations. **Recommended models by mode:** | Model | Strengths | Best for | | ------------------------ | --------------------------------------------- | ------------------------------------------- | | **GPT-5 Mini** | Balanced reasoning with low latency | **Pipeline** mode for complex reasoning | | **GPT-5 Realtime** | Ultra-low-latency voice turns | **Speech-to-Speech** and **Dualplex** | | **GPT-4o** | Strong reasoning and multimodal understanding | Complex tasks (higher latency) | | **Gemini Flash 2.0/2.5** | Ultra-fast for voice turns | **Dualplex/Multimodal** for minimal latency | **Quick selection guide:** * **Speed is critical:** Use GPT-5 Realtime or Gemini Flash 2.0/2.5 * **Rich reasoning needed:** Use GPT-4o or GPT-5 Mini with filler audios to offset latency ### LLM Temperature **Range:** 0.0 - 1.0 | **Default:** 0.1 Adjust the level of creativity of the AI when generating responses. Lower value yields better function call results. **More stable:** Predictable responses, better for function calling and business use cases **More random:** Creative and varied responses, good for casual conversations **Special behavior:** For GPT-5 Mini and GPT-5 Nano models in Pipeline mode, temperature is automatically set to 1.0 for optimal performance. ### Duration Settings Control timing and call limits to optimize user experience and costs: **Range:** 7 - 600 seconds | **Default:** 30 seconds AI will try to re-engage the user if no reply is detected within this time. **Recommended:** 30-60 seconds for professional calls. Custom prompt used when the AI tries to re-engage the user after silence. **Default:** Uses a standard re-engagement phrase like "Are you still there?" **Customization:** Write a prompt that instructs the AI how to re-engage. **Examples:** * "Gently ask if they are still there and if they need more time." * "Politely check if they have any questions." Variables like `{customer_name}` cannot be injected directly in this prompt. The AI has access to the conversation history and main system prompt, so it can reference information from there. Leave empty to use the default re-engagement behavior. **Range:** 20 - 1200 seconds | **Default:** 600 seconds (10 minutes) Call will automatically end if this value is reached. **Recommended:** 5-10 minutes for lead qualification to control costs. **Range:** 1 - 120 seconds | **Default:** 40 seconds Call will end if user doesn't reply within this time. **Recommended:** 30-45 seconds to balance patience with efficiency. **Range:** 1 - 60 seconds | **Default:** 30 seconds For how long the call will ring before marking as unanswered. **Good when you want to avoid voicemail by setting a lower value.** **Cost optimization:** Lower duration limits help control per-minute costs, especially important for high-volume campaigns. ### Call Protection Settings **Default:** Enabled Filters caller background noise for clearer speech recognition. Turn OFF if experiencing audio clipping. **Default:** Enabled Immediately ends call if voicemail is detected during outbound calls (saves costs). Prompt for the message the AI will say when voicemail is detected before ending the call. **Default:** Empty (hangs up immediately without leaving a message) **Use case:** Leave a brief message before hanging up so the recipient knows who called. **Example:** "Leave a brief voicemail message saying you called and ask them to call back." Variables like `{company_name}` cannot be injected directly in this prompt. The AI has access to the conversation history and main system prompt, so it can reference information from there. Only applies when "End Call on Voicemail" is enabled. Leave empty to hang up without a message. **Default:** Enabled Records call audio for review and analysis. **Ensure compliance with local recording laws.** **Range:** 1 - 120 seconds | **Default:** 20 seconds (when enabled) If enabled, end the call if no first user response within this time. Counts only from call start to first user response. **Use case:** Detect if anyone actually answered the phone. ## Synthesizer Settings Configure text-to-speech voice parameters for natural-sounding conversations. **Available for:** Pipeline and Dualplex modes only. Speech-to-Speech mode uses native voice generation. ### Voice Tuning Parameters Fine-tune your assistant's voice characteristics for optimal performance: **Default:** Enabled When enabled, the AI will add emotional cues to the synthesized speech based on the context of the conversation. This makes the voice sound more natural and expressive. **Effects:** * Adjusts tone based on conversation context (happy, concerned, empathetic) * Adds natural inflections and emphasis * Makes the assistant sound more human-like Disable if you prefer a more neutral, consistent tone across all conversations. **Range:** 0.0 - 1.0 | **Default:** 0.7 Lower settings make the voice more expressive but less predictable, while higher settings make it steadier but less emotional. Dynamic and varied delivery but less predictable Consistent and steady but less emotional range **Range:** 0.0 - 1.0 | **Default:** 0.5 Determines how closely the AI matches the original voice. Higher settings potentially include unwanted noise from the original recording. Cleaner audio but less accurate to original voice Accurate to original but may include background noise **For cloned voices:** Start at 0.5 and increase gradually. Higher similarity can introduce unwanted artifacts from the original recording. **Range:** 0.7 - 1.2 | **Default:** 1.0 Adjust the speed of the AI's speech for optimal comprehension and user experience. Better for complex information or older demographics Standard conversational pace for most use cases Quick conversations or time-sensitive scenarios ## Transcriber Settings Configure speech-to-text recognition for optimal accuracy and speed. **Available for:** Pipeline mode only. Speech-to-Speech and Dualplex modes use integrated transcription. ### Provider Selection Choose the best transcriber for your language and use case. The provider that will be used to transcribe the user speech. **Accuracy:** ⭐⭐⭐⭐ **Latency:** Slower Best for highest transcription fidelity when accuracy is critical. **Accuracy:** ⭐⭐⭐ **Latency:** Faster Good all-rounder for most languages. Supports multilingual configurations. **Accuracy:** ⭐⭐⭐ **Latency:** Faster Solid choice for English and major languages. Different languages, accents, or background noise can impact each provider differently. Test which performs better for your specific language and audio setup. ### Endpoint Configuration Uses AI to intelligently detect when the caller has finished speaking **Default:** Traditional voice activity detection Choose how the AI will detect the end of the user phrase ### Voice Activity Detection (VAD) Control when your assistant starts and stops talking. See [Handling interruptions guide](/conversation-design/interruptions) for detailed VAD configuration. Fine-tune these settings if experiencing interruption issues or sluggish responses. **Range:** 0 - 5 seconds | **Default:** 0.5 Adjust the time the AI will wait for the user to speak after the last word. Lower values make the AI faster, higher values are better for long user phrases. * **0 (Faster):** Quick responses but may cut off callers * **5 (Slower):** Waits longer, reduces interruptions How easily the assistant stops when caller talks over it. Controls the sensitivity for detecting when a caller is trying to interrupt. Require at least N caller words before interrupting assistant. **Use:** Prevents false triggers from background noise or brief sounds. **Available for:** Speech-to-Speech and Dualplex modes only **Range:** 0 - 1 | **Default:** Auto (model decides) Controls how sensitive the multimodal model is to detecting when the caller has finished speaking. Lower values make the assistant respond faster, higher values wait longer for the caller to finish. * **Lower (0.3-0.5):** Faster responses, good for quick conversations * **Higher (0.7-0.9):** Waits longer, better for detailed responses * **Auto:** Let the model decide based on conversation context Only visible when using Speech-to-Speech or Dualplex modes. **Pro tip:** Start with default VAD settings and adjust based on real call testing. Increase endpoint sensitivity if callers get cut off, decrease if responses feel slow. # Post-call Actions Source: https://docs.repforce.ai/ai-assistants/settings/post-call-actions Extract data from the call and send it to an app/webhook for automation workflows. Configure what happens after calls end - extract specific information from conversations and send it to external systems for further processing. ## Overview Post-call actions automatically: * Extract structured data from conversations using AI * Send extracted variables to webhooks for automation * Trigger workflows in connected platforms * Update CRM records and databases * Enable complex automation scenarios ## Post-call Variables Define the variables that the AI will extract from the call and send to a webhook. ### Variable Configuration Configure which information the AI should extract from each conversation: Create variables that the AI will identify and extract from conversations. **How extraction works:** The AI analyzes the complete call transcript and considers your system prompt context to extract the requested variables. It understands what was discussed during the call and extracts relevant information based on your variable descriptions. **Configuration:** * **Name:** Variable identifier (3-16 characters, lowercase, alphanumeric) * **Type:** Data type for the extracted value * **Description:** Clear explanation so AI understands what to extract from the conversation **Variable Types:** * **String:** Text values (names, addresses, comments) * **Number:** Numeric values (quantities, prices, scores) * **True/False:** Boolean values (yes/no answers, objectives achieved) Every assistant includes these essential variables by default: **Status (True/False):** Whether the call objective was achieved or not **Summary (String):** Call summary in a few words You can add custom variables based on your specific use case. Common variables for different scenarios: **Sales qualification:** * `budget` (Number): Customer's budget range * `decision_maker` (True/False): Is caller the decision maker * `timeline` (String): When they need the solution * `pain_points` (String): Main challenges mentioned **Appointment booking:** * `appointment_date` (String): Preferred appointment date * `service_type` (String): Type of service requested * `contact_method` (String): Preferred contact method **Support calls:** * `issue_type` (String): Category of the problem * `urgency_level` (Number): Priority score (1-10) * `resolution_status` (True/False): Was issue resolved ### Extraction Process The AI uses sophisticated analysis to extract variables from your calls: **Data sources:** * **Complete call transcript:** Everything said by both the AI and the customer * **System prompt context:** Your assistant's objectives and instructions help guide extraction * **Variable descriptions:** Clear descriptions you provide for each variable **Analysis method:** 1. AI reviews the entire conversation transcript 2. Considers the system prompt and call objectives 3. Identifies relevant information based on variable descriptions 4. Extracts and formats data according to specified types 5. Validates extracted values before sending to webhook ### Best Practices **Variable naming:** Use lowercase, alphanumeric characters only. No spaces or special characters except underscores. **Clear descriptions:** Write descriptions that clearly explain what the AI should look for in the conversation transcript. The more specific and context-aware, the better the extraction accuracy. **System prompt synergy:** Your variable descriptions work best when they align with your system prompt objectives. If your assistant is designed for lead qualification, your variables should reflect that purpose. ## Webhook Configuration Make a request to a URL that sends the extracted variables to external systems. ### Webhook Settings **Enabled/Disabled:** Control whether webhooks are sent after calls **Default:** Disabled - Enable only when you have a webhook endpoint ready to receive data **URL endpoint:** Where to send the extracted data **Format:** Must be a valid URL **Example:** `https://repforce.ai/automate/api/v1/webhooks/your-webhook-id` **Test functionality:** Built-in test feature sends sample data to verify connectivity **Send webhook only on completed:** * **Yes (Default):** Only send data for completed calls * **No:** Send data for all calls regardless of completion status **Include recording in webhook:** * **Yes (Default):** Include recording URL in the webhook payload * **No:** Send only extracted variables without recording link ### Webhook Payload The webhook will receive a comprehensive JSON payload containing call details, extracted variables, and transcript. For complete API documentation, see [Post-Call Webhook API](/api-reference/webhooks/post-call-webhook). **Key payload fields:** * **id:** Unique call identifier * **customer\_phone:** Customer's phone number (E.164 format) * **assistant\_phone:** Assistant's phone number * **duration:** Call duration in seconds * **status:** Call status (initiated, ringing, busy, in-progress, ended, completed, ended\_by\_customer, ended\_by\_assistant, unanswered, failed) * **created\_at/finished\_at:** ISO 8601 timestamps * **extracted\_variables:** AI-extracted data based on your post-call schema configuration (see [Post-call Variables](#post-call-variables) section above) * **input\_variables:** Variables passed before the call (see [Call Variables](/ai-assistants/settings/prompt-and-tools#call-variables)) * Includes default variables (status, summary) plus your custom variables * **transcript:** Detailed conversation transcript with timestamps * **formatted\_transcript:** Human-readable conversation format * **recording\_url:** Call recording URL (if enabled) * **lead:** Lead information (for campaign calls) * **campaign:** Campaign details and settings * Only included for calls that are part of campaigns **Example webhook payload:** ```json theme={null} { "id": 12345, "customer_phone": "+1234567890", "assistant_phone": "+1987654321", "duration": 125, "status": "completed", "extracted_variables": { "status": true, "summary": "Customer interested in product demo", "lead_quality": "high", "budget": 5000 }, "input_variables": { "customer_name": "John Doe", "product_interest": "Pro Plan" }, "transcript": [ { "text": "Hello! This is Sarah from RepForce.ai.", "type": "transcript", "sender": "bot", "timestamp": 1756812511.315143 }, { "text": "Hi, I'm doing well, thanks.", "type": "transcript", "sender": "human", "timestamp": 1756812514.104436 } ], "formatted_transcript": "AI: Hello! This is Sarah from RepForce.ai.\\nCustomer: Hi, I'm doing well, thanks.", "recording_url": "https://repforce.ai/storage/recordings/call-12345.mp4", "created_at": "2025-01-15T10:30:00.000000Z", "finished_at": "2025-01-15T10:32:05.000000Z" } ``` ### Testing Webhooks **Test before going live:** Use the "Make test request" button to send sample data to your webhook endpoint and verify it's working correctly. **Test process:** 1. Configure your variables and webhook URL 2. Save your assistant settings 3. Click "Make test request" 4. Check your webhook endpoint receives the test data 5. Verify the payload structure matches your expectations ## Integration Examples ### Our Automation Platform **Primary integration:** Use our built-in no-code automation platform for seamless workflows: * **Direct webhook processing:** No external setup required * **250+ app integrations:** Connect to CRM, email, calendars, and more * **Visual workflow builder:** Create complex automation without code * **Real-time data sync:** Instant processing of extracted variables * **Pre-built templates:** Ready-to-use workflows for common scenarios **Common automation workflows:** * **CRM updates:** Automatically update contact records in HubSpot, Salesforce, Pipedrive * **Email follow-ups:** Send personalized emails based on call outcomes * **Lead scoring:** Update lead scores based on extracted variables * **Calendar booking:** Schedule follow-up meetings automatically * **Team notifications:** Alert team members about important calls ### External Platforms **Any platform with webhook support:** * Receive webhook data from our platform * Process extracted variables in your own systems * Create custom automation workflows * Integrate with any API or service that accepts webhooks **Use cases:** * Connect to any CRM, email platform, or business tool * Send data to custom applications * Trigger workflows in third-party automation platforms * Store data in external databases or systems ### Custom Development **API endpoints:** Build custom receivers for webhook data **Database integration:** Store call data in your own systems **Business logic:** Trigger complex workflows based on extracted variables ## Testing Your Assistant After configuring your assistant settings, it's important to test thoroughly before deploying to production. ### Testing Methods **Web-based testing:** Use the "Speak with your assistant" button to test directly from your browser **Features:** * Real-time voice conversation through your web browser * Test all assistant capabilities including tools and knowledge base * No phone required - perfect for quick iterations * Immediate feedback on responses and behavior **Best for:** Quick testing during development and configuration **Real phone call testing:** Call your assistant from any phone number **Outbound assistants:** * If no specific number is set: Assistant calls from a random number * If caller ID is configured: Assistant calls from your specified number * Test the complete outbound flow including dialing and initial message **Inbound assistants:** * Call the assigned phone number directly * Test how the assistant handles incoming calls * Verify call routing and response quality **Best for:** Final testing with real phone conditions and audio quality ### Testing Checklist **Comprehensive testing:** Test all configured features including tools, knowledge base queries, variable extraction, and webhook delivery. **Essential tests:** * Voice clarity and response speed * Knowledge base integration (if configured) * Tool functionality (transfer, scheduling, etc.) * Variable extraction accuracy * Webhook delivery (check your endpoint receives data) * Edge cases and error handling ## Web Widget Integration Configure your assistant to work as a web widget on your website for seamless customer interactions. ### Widget Configuration **Easy integration:** Add your AI assistant to any website with a simple code snippet **Features:** * **Voice chat:** Customers can speak directly to your assistant * **Text fallback:** Option for text-based conversations * **Customizable appearance:** Match your brand colors and styling * **Mobile responsive:** Works on all devices and screen sizes **Smart interactions:** The widget adapts to your assistant configuration **Capabilities:** * Uses same knowledge base and tools as phone assistant * Supports all configured languages * Extracts same post-call variables * Sends webhooks for web conversations * Respects same system prompt and personality **Common applications:** **Customer support:** 24/7 automated support on your website **Lead qualification:** Qualify visitors before they contact sales **Appointment booking:** Allow visitors to schedule directly through the widget **FAQ handling:** Answer common questions instantly **Product demos:** Guide visitors through your product features For detailed testing guides and widget integration instructions, see our [Testing Your Assistant](/ai-assistants/testing) documentation. For detailed webhook integration guides and examples, see our [Automation documentation](/automation/overview). # Prompt & Tools Source: https://docs.repforce.ai/ai-assistants/settings/prompt-and-tools Configure your assistant's knowledge base, tools, variables, and system prompt to define its capabilities and behavior. Configure the objective of the assistant and the tools it can use during calls. ## Knowledge Base Give information to the assistant to use as a knowledge base when responding to customers. From website contents, documents, etc. ### Knowledge Base Selection Select a knowledge base store containing relevant information for the assistant to use. **Requirements:** * Must be created in your [Knowledge Bases](/conversation-design/knowledge-bases) section first * Shows status (Active, Processing, etc.) and description * Only your own knowledge bases are available Create knowledge bases from website content, PDFs, or custom documents to give your assistant domain-specific information. For comprehensive setup guide including content types, processing status, website scraping, and troubleshooting, see the complete [Knowledge Base Guide](/conversation-design/knowledge-bases). Choose how the AI will use the knowledge base. **Recommended for most cases** Uses a function call to search for information in the knowledgebase, only when needed. More accurate and efficient. **For simple use cases** Performs a search after every customer speech. More accurate but can be slower without filler audios. **Mode availability:** Speech-to-Speech and Dualplex modes only support Function Call mode. ## Custom Mid-Call Tools Create and assign your own custom tools that AI can use **mid-call** with the customer. Build tools tailored to your specific business needs: API integrations, database queries, custom workflows, and external service calls. **Quick action:** Direct link to tool creation page. Select which custom tools this assistant can use with multiple selection, search by name/description, and real-time assignment. **Scope:** Only your own tools are available. Read the [Custom Tools documentation](/ai-assistants/custom-tools) for detailed guides on creating and configuring custom tools. ## Default Tools Choose built-in tools that AI can use **mid-call** with the customer. Route calls to multiple destination phone numbers like different people or departments according to your flow. **Use cases:** * Escalation to human agents * Department routing * Specialist handoffs **Configuration options:** * **Standard mode:** Use regular phone numbers (e.g., +1234567890) * **Advanced mode:** Use SIP URI format for SIP providers (e.g., sip:+1234567890\@sip-server) **For SIP integrations:** * Set transfer to "Advanced" mode * Use SIP URI format: `sip:number@sip-server` * Verify your SIP provider supports SIP REFER * Test with different URI formats if transfers fail **Prompt instruction:** Include in your system prompt something like "call the transfer function when the user requests to speak with someone else" to ensure the AI uses this tool appropriately. If transfers aren't working, see our [SIP Integration troubleshooting guide](/troubleshooting/sip-integration#transfer-phone-call-not-working) for detailed solutions. Ends the call when the conversation is complete. **Use cases:** * Natural conversation conclusion * Objective achieved * Customer satisfaction confirmed **Prompt instruction:** If the AI doesn't call the end call function automatically, include in your system prompt "call the hang\_up function to close the call" when the conversation should end. Easily send keypad inputs during outbound calls, enabling smooth navigation through IVR menus and automated workflows. The AI navigates using keypad buttons when calling and responding to prompts. **Use cases:** * Navigate phone menus * Enter extension numbers * Input security codes * IVR system navigation **Prompt instruction:** Include in your system prompt instructions about when to use DTMF input, such as "use the send\_dtmf tool to navigate phone menus when needed to reach the right person." For detailed information about DTMF capabilities, see [Tools & Functions](/ai-assistants/tools-and-functions#4-dtmf-input). Real-time booking scheduling integration with multiple calendar platforms. **Available integrations:** * **Cal.com:** Full setup guide available at [Cal.com Scheduling](/ai-assistants/cal-com-scheduling) * **GoHighLevel:** Complete integration guide at [GoHighLevel Scheduling](/ai-assistants/gohighlevel-scheduling) * **Calendly:** Full setup guide available at [Calendly Scheduling](/ai-assistants/calendly-scheduling) **Use cases:** * Book appointments with calendars * Check real-time availability * Send automatic confirmation details * Sync with existing calendar systems **Setup:** 1. Select your calendar provider (Cal.com, GoHighLevel, or Calendly) 2. Authenticate with your calendar account 3. Choose the event type/calendar to use for bookings 4. The AI will automatically check availability and book appointments Available when calendar integration is enabled in your platform settings. ## Call Variables Define variables that can be passed **before** making the call and used in the prompt **like **. ### Variable Configuration Create call variables to pass information to your assistant before the call starts. **Setup process:** * Define variable names and default values * Pass values when creating calls/leads or importing clients * Variables available immediately in prompts and during calls * Use for personalization and context **Configuration:** * **Variable name:** The identifier (e.g., `customer_name`) * **Default value:** Used when not passed (e.g., "John") How to use call variables in your assistant: **In system prompts:** * Reference variables with `{variable_name}` syntax * Personalize conversations dynamically * Provide context-specific information **Examples:** * `{customer_name}` for personalization ("Hello ") * `{email}` for calendar integrations * `{account_type}` for tailored responses * `{company}` for business context Ways to populate call variables: **Manual entry:** * When creating individual calls * Through campaign lead creation **Import methods:** * CSV import with variable columns * API integration with client data * Direct CRM synchronization **Automation platform integrations:** * **GoHighLevel (GHL):** Automatically pull contact data and custom fields * **Google Sheets:** Import leads with variables from spreadsheet columns * **Connect with 250+ popular tools** and platforms using our no-code platform * **Any other platform** through webhooks for custom integrations **Platform integration:** * Automatically populated from client profiles * Connected to existing customer databases * No-code automation workflows Call variables are essential for personalizing AI conversations. They allow the AI to use specific customer information during calls, making interactions more relevant and effective. ## Call Flow Configuration ### Who Speaks First? Control whether your assistant or the customer initiates the conversation. **Default behavior:** Assistant starts the conversation The AI will immediately greet the caller and begin the conversation flow as soon as the call connects. **Best for:** Most outbound scenarios, sales calls, appointment reminders **Wait for customer:** Assistant listens first If you choose "Customer", the AI will wait for the customer to speak first before responding. **Best for:** Inbound support calls, reception scenarios, reactive assistance ### Initial Message Configure the first thing your assistant says when the call begins. Write the opening message your assistant will speak at the start of each call. **Best practices:** * Keep it concise and friendly * Introduce your company/purpose clearly * Set expectations for the conversation * Use variables for personalization (e.g., `{customer_name}`) **Example:** "Hi , this is Sarah from ABC Company. I'm calling to follow up on your recent inquiry about our services. Do you have a moment to chat?" **Optional:** Upload a custom audio file instead of text-to-speech **Requirements:** * MP3 or WAV format * Clear, high-quality recording * Professional voice and tone * Matches your assistant's voice if using voice cloning **Benefits:** * Perfect pronunciation and delivery * Consistent brand voice * Professional first impression * No text-to-speech latency for opening This works best if the AI voice is cloned using the same voice used in the initial audio. See our [Initial Message guide](/ai-assistants/initial-message) for detailed best practices and examples. ## System Prompt Define the assistant's personality, objectives, and behavior guidelines. ### Editing Tools Choose the editing experience that works best for you: **Chat-based editing with AI assistance** Describe changes in plain language and let AI suggest intelligent modifications. Review and accept/reject each change individually. **Best for:** Quick iterations, improving existing prompts, text-focused editing **Visual drag-and-drop editor** Design conversation flows by connecting nodes on a canvas. Create branching logic and multi-path decision trees visually. **Best for:** Complex call flows, structured scripts, visual thinkers Both tools store the prompt in the same field - switching between them is possible but may require adjustments. ### Prompt Configuration Write your own system prompt from scratch * Full control over assistant behavior * Tailored to specific use cases * Markdown formatting supported Start with pre-built templates * Multiple languages available * Different conversation types * Proven effective prompts ### Best Practices Clearly define the assistant's role, objectives, and constraints. **Include:** * Who the assistant represents * What they're trying to achieve * What they should/shouldn't do Define what topics and actions are off-limits. **Consider:** * Data privacy requirements * Legal compliance * Brand guidelines Provide sample conversations to guide behavior. **Examples help with:** * Tone and style * Response length * Handling objections See our [System Prompt guide](/ai-assistants/system-prompt) for detailed best practices and examples. # System Prompts Source: https://docs.repforce.ai/ai-assistants/system-prompt Learn how to create effective system prompts - the core intelligence of your AI assistant The system prompt is the most crucial component of your AI assistant. It defines your assistant's personality, behavior, knowledge, and capabilities. Think of it as the "brain" and "training manual" combined. ## Editing Options You have three ways to create and edit your system prompt: System Prompt Editing Options Chat with AI to edit your prompt. Best for quick iterations and improvements. Visual drag-and-drop editor. Best for structured, multi-path conversations. Direct text editing. Best for full control and manual fine-tuning. ## Quick Start with Templates To get started quickly: 1. Go to your [assistant settings](/ai-assistants/settings/prompt-and-tools#system-prompt) 2. Find the system prompt field 3. Click the "Templates" button nearby 4. Choose a template that matches your use case 5. Customize it for your needs ## Language Support Your system prompt can be written in any language, regardless of the spoken language setting: * Write the prompt in your preferred language * Set the spoken language separately in [assistant settings](/ai-assistants/settings/general#language-configuration) * The AI will follow the prompt's instructions while speaking in the selected language For example: * System prompt in English, spoken language set to Spanish * System prompt in German, spoken language set to French * System prompt in Chinese, spoken language set to English ## Why They Matter Your system prompt: * Shapes how the AI thinks and responds * Defines conversation boundaries * Provides essential knowledge * Controls behavior and tone * Determines handling of edge cases ## Key Components A good system prompt should include: ### 1. Role & Identity ``` You are a professional sales representative for [Company]. You specialize in [Product/Service] and have extensive knowledge of our offerings. ``` ### 2. Conversation Style ``` Maintain a friendly, professional tone. Use clear, concise language. Avoid technical jargon unless specifically asked. ``` ### 3. Key Information ``` Our main products are: - Product A ($X/month): [features] - Product B ($Y/month): [features] Current promotion: 20% off first 3 months ``` ### 4. Behavioral Guidelines ``` - Always verify customer information before discussing account details - Transfer to a human agent if the customer seems frustrated - Don't make promises about delivery dates ``` ### 5. Response Framework ``` When asked about pricing: 1. First understand their needs 2. Present relevant package options 3. Explain the value proposition 4. Share any applicable discounts ``` ## Best Practices 1. **Be Specific** * Clear instructions get better results * Include examples of good responses * Define what NOT to do 2. **Structure Matters** * Organize information logically * Use bullet points and sections * Keep related information together 3. **Test and Iterate** * Start with a basic prompt * Test various scenarios * Refine based on call recordings * Add handling for edge cases ## Common Mistakes * **Too Vague**: "Be helpful and professional" (Not specific enough) * **Too Rigid**: Scripting every possible response (Reduces natural flow) * **Information Overload**: Including unnecessary details * **Missing Guidelines**: Not specifying how to handle common situations ## Example Structure ``` # Role and Purpose [Define who the AI is and its main goals] # Core Knowledge [Essential information about products/services] # Conversation Guidelines [How to interact with customers] # Response Patterns [How to handle specific situations] # Limitations and Boundaries [What the AI should NOT do] ``` ## Testing Your Prompt 1. Make test calls covering: * Common scenarios * Edge cases * Difficult situations * Various customer personalities 2. Review and adjust: * Listen to call recordings * Check response accuracy * Verify tone consistency * Test knowledge retention ## Optimization Tips * Start with Fast Engine for quick iterations * Use call recordings to identify gaps * Add examples of good/bad responses * Include handling for unexpected questions *** **Pro Tip:** Your system prompt is a living document - regularly update it based on actual call experiences and customer interactions. # Test Chat Interface Source: https://docs.repforce.ai/ai-assistants/test-chat Test your assistant with a text-based chat interface for rapid iteration The Test Chat interface provides a quick way to test your assistant's conversation flow without making actual phone calls. ## Accessing Test Chat 1. Navigate to your assistant's page 2. Click the **"Test Assistant"** button with the chat icon 3. A chat interface will open in a slide-over panel Test Assistant Button ## How It Works The Test Chat interface simulates a conversation with your assistant: * **Text-based interaction:** Type messages instead of speaking * **Real AI responses:** Your assistant processes messages using the same logic as phone calls * **Variable testing:** Test how your assistant handles variables and data collection * **Tool execution:** See how your assistant uses configured tools and functions * **Fast iteration:** Quickly test prompt changes without phone calls ## When to Use Test Chat **Ideal for:** * Testing conversation flow and logic * Verifying prompt behavior and responses * Debugging variable collection * Testing tool/function calls * Rapid prompt iteration **Not suitable for:** * Testing voice quality or speech recognition * Testing call transfers (use phone testing) * Testing phone-specific features * Evaluating conversation timing and pacing ## Testing Workflow **1. Test conversation flow with chat interface:** * Verify your assistant understands user intents * Check that variables are collected correctly * Ensure tools execute as expected * Validate response quality **2. Test voice quality with Web Call:** * Verify voice clarity and tone * Check response timing and pacing * Test interruption handling **3. Final testing with Phone Call:** * Test all features including call transfers * Verify real-world call quality * Test edge cases and error handling Test Chat creates conversation records that appear in your **Conversations** page, helping you review and analyze test sessions. ## Cost Considerations Test Chat interactions: * Use AI processing credits from your account balance * Are typically more cost-effective than phone testing * Allow for faster iteration with immediate feedback * Create conversation records for later review Use Test Chat for initial prompt development, then move to phone testing for final validation before deploying to production. # Testing Your Assistant Source: https://docs.repforce.ai/ai-assistants/testing Learn how to quickly test your AI assistant for both inbound and outbound calls There are multiple ways to test your AI assistant, depending on whether you want to test inbound or outbound functionality and your preferred testing method. ## Web Call Testing **Browser-based voice testing** with the "Speak with your assistant" button: 1. Go to your assistant dashboard 2. Click "Speak with your assistant" button 3. Test voice conversation directly in your browser 4. Evaluate voice quality, response timing, and conversation flow **Pros:** * Instant voice testing without phone setup * Tests voice components and timing * Easy access from dashboard **Cons:** * Call transfer functionality will not work during web testing **Cost Notice:** Web call testing deducts 1 minute from your account balance per minute of call for AI processing costs. This is not free testing. ## Phone Call Testing **Real phone call testing** for outbound capabilities: 1. Go to your assistant's settings 2. Find the "Speak to your assistant" purple button 3. Enter your phone number 4. Click to initiate the test 5. You'll receive a call from your AI assistant immediately ## Testing Inbound Calls **Real phone call testing** for inbound functionality: 1. Make sure you have a phone number assigned to your assistant 2. Call that number from any phone 3. Your AI assistant will answer and handle the call ## Testing Best Practices **Start with web calls** for quick iteration: * Test basic conversation flow and voice quality * Verify prompt behavior and response timing * Note: Call transfers won't work in web testing **Move to phone calls** for comprehensive testing: * Test all tools including call transfers * Verify real-world call quality and timing * Test edge cases and interruption handling **Cost Management:** * Both web and phone testing use account balance * Plan your testing sessions to manage costs * Use text-based prompt testing first when possible *** **Tip:** Save your AI's phone number in your contacts to easily make inbound test calls whenever needed. # Tools & Functions Source: https://docs.repforce.ai/ai-assistants/tools-and-functions Explore the built-in tools and functions that enhance your AI assistant's capabilities during calls RepForce.ai offers built-in "tools" that your AI assistant can use during a call. These help you shape the conversation flow and automate actions like transferring calls or scheduling appointments. ## 1. End Call Tool * **Purpose**: Tells the AI to politely wrap up the conversation. * **How It Works**: You can specify in the system prompt or logic, for instance: "If the user says `goodbye`, end the call." * **Configuration**: Enable in [Prompt & Tools settings](/ai-assistants/settings/prompt-and-tools#default-tools) and define conditions in your system prompt that should trigger the end call. ## 2. Transfer Tool * **Purpose**: Moves the caller from the AI assistant to a human agent or external phone number. * **Use Cases**: Warm leads on a sales call, escalations on a support call, etc. * **Configuration**: Set up in [Prompt & Tools settings](/ai-assistants/settings/prompt-and-tools#default-tools) by adding the phone number or department the call should go to, and optionally a short hold message. ## 3. Appointment Scheduler * **Purpose**: Lets the AI check your calendar availability and book appointments automatically. * **Available Integrations**: Cal.com, GoHighLevel, and Calendly calendar systems * **Typical Flow**: 1. AI offers scheduling. 2. Caller selects date/time. 3. AI confirms and sends a confirmation (using email or SMS if configured). * **Configuration**: Set up in [Prompt & Tools settings](/ai-assistants/settings/prompt-and-tools#default-tools) with your calendar integration. ## 4. DTMF Input * **Purpose**: Allows the AI to send keypad inputs during calls to navigate phone menus, IVR systems, and automated workflows. * **How It Works**: The AI can press phone keypad buttons (0-9, \*, #) when encountering automated systems or menu prompts. * **Use Cases**: * Navigate through company phone menus * Enter extension numbers to reach specific departments * Input security codes or account numbers * Bypass IVR systems to reach human agents * **Configuration**: Enable in [Prompt & Tools settings](/ai-assistants/settings/prompt-and-tools#default-tools) and include instructions in your system prompt about when to use DTMF. ## 5. No-Code Automation Platform * **Purpose**: After calls, the AI can trigger actions in the automation platform (like updating a CRM, sending an email, or logging results in Google Sheets). * **Configuration**: Set up triggers and actions in the [Automation Platform](/automation-platform/introduction), then link to your assistant via webhook configuration in [Post-call Actions](/ai-assistants/settings/post-call-actions#webhook-configuration). ## 6. Custom Mid-Call Tools * **Purpose**: Create your own custom API integrations that the AI can use during calls. * **Use Cases**: Check inventory, verify customer data, fetch real-time information, or integrate with your own systems. * **Configuration**: Set up in [Prompt & Tools settings](/ai-assistants/settings/prompt-and-tools#custom-mid-call-tools) by defining API endpoints, parameters, and when the AI should use them. * For detailed setup instructions and examples, see our [Custom Mid-Call Tools Guide](/ai-assistants/custom-tools). *** **Note:** Tools can be combined. For instance, the AI can use a custom tool to check availability, then schedule an appointment, and finally transfer to a human agent if needed. # Voice Selection & Voice Cloning Source: https://docs.repforce.ai/ai-assistants/voice-selection Learn how to select built-in voices or clone your own voice for your AI assistants Your AI assistant can speak with **built-in voices** or a **custom cloned voice**. Natural, realistic voices increase customer trust and engagement. ## TTS Provider Select your Text-to-Speech provider in the assistant settings. Available in **Pipeline** and **Dualplex** modes. **Available Providers:** * **ElevenLabs** - High-quality voices * **Cartesia** - Fast, low-latency synthesis The TTS Provider dropdown appears after selecting a language. ## Voice Library Each TTS provider has its own voice library. Select male/female, accent, or language based on your provider. ## Voice Cloning Clone a voice from an audio sample. Available in **Pipeline** and **Dualplex** modes. **Clone to Provider:** * **Cartesia** - Single audio file, at least 10 seconds, 1 speaker, no background noise * **ElevenLabs** - Samples over 1 minute, 1 speaker, no background noise. Max 5 minutes total. Quality over quantity. **Steps:** 1. Click "Clone voice" next to voice selector 2. Select provider (Cartesia or ElevenLabs) 3. Choose the voice language 4. Enter a name for your voice 5. Record or upload audio 6. Wait for processing 7. Select your new voice from dropdown ## Best Practices 1. **High-Quality Audio**: Clearer samples give better results 2. **Steady Delivery**: Natural tone, no abrupt changes 3. **No Background Noise**: Record in a quiet environment 4. **Legal**: Ensure permission to clone voices that aren't yours *** **Tip:** After selecting or cloning a voice, do a test call to confirm it sounds as expected. # Web Widget Source: https://docs.repforce.ai/ai-assistants/web-widget Embed your AI assistant on your website with voice and chat capabilities Add your AI assistant to any website with a customizable widget that supports voice calls, text chat, or both. ## Overview The Web Widget allows website visitors to interact with your AI assistant directly through: * **Voice conversations:** Real-time voice calls in the browser * **Text chat:** Messaging interface for text-based interactions * **Hybrid mode:** Seamless switching between voice and chat ## Accessing Widget Configuration 1. Navigate to your assistant's edit page 2. Click the **"Web widget"** button (yellow/warning color) 3. The widget configuration panel opens with live preview Web Widget Button Location Web Widget is a premium feature. Ensure your plan includes web widget access before configuration. ## Widget Modes Choose how visitors interact with your assistant: ### Voice & Chat (Recommended) Users can seamlessly switch between voice and text during conversations. **Best for:** * Maximum flexibility for users * Accessibility (voice for mobile, chat for quiet environments) * Complex interactions requiring both modes ### Chat Only Text-based messaging interface only. **Best for:** * Customer support and FAQs * Environments where voice isn't appropriate * Lead capture and qualification forms ### Voice Only Real-time voice conversations only. **Best for:** * Phone-like experience on website * Voice-first use cases * Hands-free interactions ## Configuration Options ### General Tab Widget General Tab **Widget Mode:** Voice, Chat, or Voice & Chat **Widget Size:** Choose between standard or **extra large** layout * **Standard**: Compact floating widget suitable for most use cases * **Extra Large**: Half-screen panel on desktop, full-screen on mobile — ideal for detailed conversations **Position:** Choose from 8 positions (bottom-right, bottom-left, bottom-center, middle-right, middle-left, top-right, top-left, top-center) **Primary Color:** Brand color for buttons and accents **Toggle Button Size:** Small or Normal **Toggle Button Style:** Animated (glass morphism) or Simple (flat design) **Auto-Open on Page Load:** When enabled, the widget automatically expands when the page loads — no click required from the visitor. ### Button Tab Widget Button Tab **Custom Avatar:** Upload your own avatar image to replace the default widget icon. Appears on the toggle button and in the chat header. Max file size: 512KB, 1:1 aspect ratio (square). **Button Main Text** (default: "Need help?") — primary text on the widget button **Button Sub Text** (default: "Chat with us") — secondary text, hidden when using the small button size **Tab Labels (Voice & Chat mode only):** * Voice Tab Label (default: "Voice") — rename to match your brand language (e.g., "Call Us", "Speak") * Chat Tab Label (default: "Chat") — rename to match your brand language (e.g., "Message", "Text") ### Header & Modal Tab Widget Header & Modal Tab **Header Title** (default: "AI Assistant") **Header Subtitle** (default: "Ready to help you ✨") **Modal Title** (default: "Ready to chat?") **Start Button Text** (default: "Start Voice Chat") **Modal Description** (default: "Click below to start your conversation") ### Chat Settings Tab Widget Chat Settings Tab This tab is only visible when the widget mode includes chat (Chat Only or Voice & Chat). **Chat Placeholder** (default: "Type your message...") **Send Button Label** (default: "Send message") — accessibility label for the send button **Show Function Calls:** When disabled (default), LLM tool calls (e.g., calendar lookups, knowledge base queries) are hidden from the chat, keeping the conversation clean for end users. Enable to show tool usage details. ### Clickable Links in Chat The chat widget supports **markdown formatting**, so your AI assistant can send clickable links, bold text, lists, and more. To include clickable URLs in chat messages, use markdown link format in your assistant's prompt or initial message: ``` Check out our [latest offers](https://example.com/offers) or visit our [help center](https://example.com/help). ``` Add an instruction to your assistant's prompt like: *"When sharing links or URLs, always format them as clickable markdown links: [link text](url)"* — this ensures the AI consistently outputs clickable links instead of plain text URLs. ### Voice Settings Tab Widget Voice Settings Tab This tab is only visible when the widget mode includes voice (Voice Only or Voice & Chat). **Connecting Text** (default: "Connecting...") **Disconnect Text** (default: "Disconnect") **Error Text** (default: "Connection failed. Please try again.") ### Pre-Chat Form Pre-Chat Form Configuration Collect information before starting conversations: **Form Configuration:** * Pre-form Title (default: "Before we start...") * Pre-form Description (default: "Please provide some information to help us assist you better") * Submit Button Text (default: "Continue") **Form Fields:** Add custom fields to collect data: * **Variable Name:** Internal variable name (maps to assistant variables). Only letters, numbers, dashes, and underscores allowed. * **Field Label:** Display label shown to users * **Field Type:** Text, Email, Phone, or Textarea * **Required:** Make field mandatory * **Placeholder:** Placeholder text shown in the field * **Helper Text:** Optional description below the field **Variable Mapping:** Form field names automatically map to your assistant's variables, making collected data available during conversations. **Example Form Fields:** ``` Name: Full Name (required, text) Email: Email Address (required, email) Company: Company Name (optional, text) Message: How can we help? (optional, textarea) ``` ### AI Response Settings Widget AI Response Settings **AI Enabled:** When toggled on (default), the AI assistant automatically responds to incoming messages. Turn this off if you want to use the widget for manual-only conversations — messages are collected but the AI does not reply. ### Conversation Webhook Widget Conversation Webhook **Webhook URL:** Enter a URL to receive a webhook notification whenever a new conversation starts via the widget. Use this to trigger automation flows, log events to your CRM, or notify your team in real-time. ### Widget Display Widget Display Toggle **Enable Widget:** Master toggle that controls whether the widget loads on your website. When disabled, the widget will not appear even if the embed script is installed on your site. Use this to temporarily hide the widget without removing code from your website. ## Live Widget Preview Widget Live Preview At the top of the configuration panel, a live preview shows exactly how your widget will look and behave on a website. The preview updates in real-time as you change any setting. **Copy Preview URL** — copies the preview URL to your clipboard so you can open it in a separate browser tab or share it with your team for review. **Reset Data** — clears all stored conversation history, form submissions, and preferences in the preview. Use this to simulate a first-time visitor experience after testing. The preview is fully interactive — you can click the widget button, fill out the pre-chat form, and start a real conversation to test your configuration before deploying. ### Embed Code Widget Embed Code The embed code section provides a ready-to-copy script tag. Click **Copy** to copy it to your clipboard, then paste it into your website before the closing `` tag: ```html theme={null} ``` Save your widget settings **before** copying the embed code. The script loads all configuration from the server, so any unsaved changes won't appear on your website. ## Installation 1. Configure and save your widget settings 2. Copy the embed code from the **Embed Code** section 3. Paste the script tag before the closing `` tag on your website 4. Visit your website and verify the widget appears in the configured position 5. Test voice/chat functionality and pre-chat form (if configured) ## Widget Behavior ### First Visit * Widget button appears in configured position * Click opens modal/chat interface * Pre-chat form displays (if configured) * After form submission, conversation starts ### Return Visits * Previous conversation state may be restored * Form data remembered (if visitor hasn't cleared cookies) * Seamless continuation of support experience ### Conversation Tracking All widget conversations appear in your [Conversations](/conversations/overview) page for review and analysis. HTTPS (SSL certificate) is required for voice functionality. HTTP sites can only use chat mode due to browser security restrictions. ## Troubleshooting For setup and configuration issues, see [Web Widget Troubleshooting](/troubleshooting/web-widget). ## Next Steps * Test widget using the live preview * Embed code on your website * Monitor conversations in the [Conversations](/conversations/overview) page # What is an AI Assistant? Source: https://docs.repforce.ai/ai-assistants/what-is-ai-assistant Understand what an AI Assistant is, its key components, and how it can help automate your phone interactions An **AI Assistant** (sometimes called an agent) is your configurable bot that speaks with customers or leads over the phone—either when they call you (**inbound**) or when your system calls them (**outbound**). ## Why Use an AI Assistant? * **Automate Common Interactions**: Answer FAQs, book appointments, or qualify leads 24/7. * **Reduce Workload**: Free your human team from repetitive tasks like verifying contact info or taking messages. * **Scalable**: One assistant can handle many calls in parallel, allowing you to grow without adding more agents. ## Key Components 1. **System Prompt**: The core instructions guiding how your assistant behaves. 2. **Initial Message**: The very first phrase the AI says (especially critical for inbound calls). 3. **Voice Settings**: Choose a built-in voice or clone your own. 4. **Tools** (Optional): Transfer, end call, scheduling, and more. *** **Next Steps** * Learn how to [Create and Edit an AI Assistant](/ai-assistants/settings/general). * Explore the various [Tools & Functions](/ai-assistants/tools-and-functions) you can add to your assistant. # Generate AI Reply Source: https://docs.repforce.ai/api-reference/ai/generate-reply POST /user/ai/generate-reply Generate an AI response using an assistant, identified by an external customer identifier This endpoint generates an AI response for a given message using your configured assistant. It automatically creates or reuses conversations based on the customer identifier, making it ideal for integrating AI responses into external platforms, CRMs, or custom chat interfaces. **Rate Limited** — This endpoint is rate limited to 5 requests per minute per API token to prevent abuse. ### Request Body The ID of the assistant to use for generating the response. Must belong to your account. A unique identifier for the customer. This is used to maintain conversation context across multiple messages. Examples: phone number, email address, CRM contact ID, Facebook user ID. Maximum length: 255 characters. The customer's message to respond to. Optional context variables to pass to the assistant. These are merged with any existing conversation variables. Useful for passing customer data, session context, or other metadata. ### Response Fields Indicates whether the request was successful The UUID of the conversation. Use this to track or reference the conversation later. The customer identifier provided in the request The AI-generated response to the customer's message Array of function calls made by the assistant while processing the message. Empty array if no functions were called. The name of the function that was called The arguments passed to the function The result returned by the function Indicates if AI responses are disabled for this conversation (e.g., due to manual takeover) ### Error Responses Will be `false` when an error occurs Error message describing what went wrong Machine-readable error code. Possible values: * `ASSISTANT_NOT_FOUND` - The assistant ID is invalid or doesn't belong to your account * `INSUFFICIENT_BALANCE` - Your account balance is too low to process the message ```bash cURL theme={null} curl -X POST "https://app.repforce.ai/api/user/ai/generate-reply" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "assistant_id": 123, "customer_identifier": "+14155551234", "message": "Hi, I would like to schedule an appointment", "variables": { "customer_name": "John Smith", "source": "whatsapp" } }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://app.repforce.ai/api/user/ai/generate-reply', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ assistant_id: 123, customer_identifier: '+14155551234', message: 'Hi, I would like to schedule an appointment', variables: { customer_name: 'John Smith', source: 'whatsapp' } }) }); const data = await response.json(); console.log(data.reply); ``` ```python Python theme={null} import requests response = requests.post( 'https://app.repforce.ai/api/user/ai/generate-reply', headers={ 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, json={ 'assistant_id': 123, 'customer_identifier': '+14155551234', 'message': 'Hi, I would like to schedule an appointment', 'variables': { 'customer_name': 'John Smith', 'source': 'whatsapp' } } ) data = response.json() print(data['reply']) ``` ```php PHP theme={null} $response = Http::withToken('YOUR_API_TOKEN') ->post('https://app.repforce.ai/api/user/ai/generate-reply', [ 'assistant_id' => 123, 'customer_identifier' => '+14155551234', 'message' => 'Hi, I would like to schedule an appointment', 'variables' => [ 'customer_name' => 'John Smith', 'source' => 'whatsapp' ] ]); $reply = $response->json()['reply']; ``` ```json 200 Success theme={null} { "success": true, "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "customer_identifier": "+14155551234", "reply": "Hi John! I'd be happy to help you schedule an appointment. What day and time work best for you?", "function_calls": [], "ai_disabled": false } ``` ```json 200 Success (With Function Calls) theme={null} { "success": true, "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "customer_identifier": "+14155551234", "reply": "I've checked our calendar and we have availability tomorrow at 2 PM and Friday at 10 AM. Which works better for you?", "function_calls": [ { "name": "check_availability", "arguments": { "start_date": "2025-01-08", "days": 7 }, "result": { "slots": ["2025-01-08 14:00", "2025-01-10 10:00"] } } ], "ai_disabled": false } ``` ```json 404 Assistant Not Found theme={null} { "success": false, "error": "Assistant not found or does not belong to you", "error_code": "ASSISTANT_NOT_FOUND" } ``` ```json 402 Insufficient Balance theme={null} { "success": false, "error": "Insufficient balance. Please top up your account.", "error_code": "INSUFFICIENT_BALANCE" } ``` ```json 422 Validation Error theme={null} { "message": "The assistant id field is required.", "errors": { "assistant_id": ["The assistant id field is required."] } } ``` ```json 429 Rate Limited theme={null} { "message": "Too Many Attempts.", "retry_after": 60 } ``` ## Use Cases ### Multi-Channel AI Responses Use this endpoint to add AI responses to any messaging platform: 1. Receive a message from WhatsApp, Facebook, SMS, or any other channel 2. Call this endpoint with the message and customer identifier 3. Send the AI response back through the original channel ### CRM Integration Integrate AI responses into your CRM or helpdesk: 1. Use the CRM contact ID as the `customer_identifier` 2. Pass customer data as `variables` for personalized responses 3. The conversation persists across sessions using the same identifier ### Custom Chat Interfaces Build your own chat interface powered by your RepForce.ai assistant: 1. Generate a unique identifier for each user session 2. Send messages through this endpoint 3. Display the AI responses in your interface ## Conversation Persistence Conversations are automatically persisted based on the `assistant_id` and `customer_identifier` combination: * **Same identifier**: Messages are added to the existing conversation, maintaining full context * **New identifier**: A new conversation is created for the customer * **Variables merge**: When variables are provided, they are merged with existing conversation variables ## Best Practices 1. **Use consistent identifiers**: Always use the same format for customer identifiers (e.g., always E.164 for phone numbers) 2. **Pass relevant context**: Use the `variables` field to provide customer data that helps the AI personalize responses 3. **Handle rate limits**: Implement retry logic with exponential backoff for rate-limited requests 4. **Store conversation IDs**: Save the returned `conversation_id` for later reference or debugging 5. **Monitor costs**: Track usage to manage costs, especially for high-volume integrations # Create assistant Source: https://docs.repforce.ai/api-reference/assistants/create-assistant POST /user/assistant Create a new AI assistant with specified configuration This endpoint allows you to create a new AI assistant with comprehensive configuration options. ## Engine Modes The API supports three engine modes, each with different capabilities: | Mode | Description | Required Fields | | ------------ | ------------------------------------ | --------------------- | | `pipeline` | Traditional STT → LLM → TTS pipeline | `llm_model_id` | | `multimodal` | Real-time multimodal AI | `multimodal_model_id` | | `dualplex` | Multimodal brain + custom TTS voice | `multimodal_model_id` | ### Request Body #### Core Required Fields The name of the assistant (max 255 characters) The voice ID to use for the assistant. Use the [Get Voices](/api-reference/assistants/get-voices) endpoint with the `mode` parameter to get compatible voices for your engine mode. The language ID for the assistant. Use the [Get Languages](/api-reference/assistants/get-languages) endpoint to get available languages. The assistant type. Options: `inbound`, `outbound` The engine mode. Options: `pipeline`, `multimodal`, `dualplex` The timezone for the assistant (e.g., "Europe/Bucharest", "America/New\_York") The initial message the assistant will speak when the call starts (max 200 characters) The system prompt that defines the assistant's behavior and personality #### Mode-Specific Fields The LLM model ID to use. **Required for `pipeline` mode.** Use the [Get Models](/api-reference/assistants/get-models) endpoint to get available models. The multimodal model ID. **Required for `multimodal` and `dualplex` modes.** Use the [Get Models](/api-reference/assistants/get-models) endpoint to get available multimodal models. Fallback LLM model ID for tool calls in multimodal/dualplex modes. Optional. Turn detection sensitivity for multimodal/dualplex modes (0-1). Default: auto #### Secondary Languages Array of additional language IDs the assistant can speak. The assistant will auto-detect and switch languages. ```json theme={null} "secondary_language_ids": [2, 3, 4] ``` #### Knowledgebase Settings The knowledgebase ID to attach to this assistant How to use the knowledgebase. Options: * `function_call` - AI calls a function to search (required for multimodal/dualplex) * `prompt` - Knowledge is injected into prompt (pipeline only) #### Phone Number The ID of a phone number to assign to the assistant. Must belong to your account. For `inbound` assistants, the phone number cannot be a Caller ID type and cannot be already assigned to another inbound assistant. #### Custom Mid-Call Tools Array of custom mid-call tool IDs to attach. Each tool must belong to your account. ```json theme={null} "tool_ids": [1, 5, 12] ``` #### Built-in Tools Array of built-in tools to enable. Each tool has a `type` and tool-specific fields. **call\_transfer** - Transfer the call to another phone number * `phone_number` (required): Phone number to transfer to (e.g., "+1234567890") * `description`: When to transfer the call * `custom`: If true, AI can determine transfer number dynamically * `timezone`: Timezone for transfer availability * `warm_transfer`: Send a message to the customer before transferring (default: `false`) * `warm_transfer_message`: Prompt telling the AI what to say before transferring (e.g., "Tell the customer that the call is being transferred.") **warm\_call\_transfer** - Warm transfer with supervisor briefing * `supervisor_phone` (required): Phone number to dial for the warm transfer (e.g., "+14155552001"). If `custom_sip` is enabled, this is a SIP address or internal extension instead. * `outbound_phone_id` (required): ID of the phone number used to dial the supervisor. Use [Get Phone Numbers](/api-reference/assistants/get-phone-numbers) to find available numbers. * `description` (required): **When to transfer** — describes when the AI should initiate the warm transfer (e.g., "Transfer the call to a human supervisor when the customer requests to speak with a real person.") * `custom_sip`: Enable to enter a custom SIP address or internal extension instead of a phone number (default: `false`) * `caller_id_mode`: What phone number the supervisor sees when receiving the call. Options: `outbound_number` (default — shows the outbound phone number), `customer_number` (shows the caller's number), `custom` (shows a custom number) * `custom_caller_id`: Custom phone number shown to supervisor. Only used when `caller_id_mode` is `custom`. * `hold_music`: Audio played to the caller while on hold. Options: `hold_music` (default — plays default hold music), `none` (silence, no music) * `hold_music_volume`: Volume level for hold music, 0-100 (default: `80`) * `hold_message`: Message spoken to caller before placing them on hold (default: "Please hold while I connect you with a supervisor.") * `summary_instructions`: Instructions for how the AI should brief the supervisor about the call (default: "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).") * `briefing_initial_message`: The first message the AI says to the supervisor when they answer (default: "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?") * `connected_message`: Message spoken to caller after supervisor is connected (default: "You are now connected with a supervisor. I'll leave you to it.") **end\_call** - End the call programmatically * `description`: When the AI should end the call **dtmf\_input** - Send DTMF tones (keypad input) * `description`: When to use DTMF input (for IVR navigation) **collect\_keypad** - Collect keypad input from the caller * `timeout`: Seconds to wait for input, 1-30 (default: 5) * `stop_key`: Key that ends input. Options: `#` (default), `*` **calendar\_integration** - Schedule appointments via Cal.com * `calcom_api_key` (required): Your Cal.com API key * `calcom_event_slug` (required): The event type slug from Cal.com * `calcom_team_slug`: Team slug if the event belongs to a Cal.com team * `calcom_endpoint`: Cal.com API region. Options: `us` (default — `https://api.cal.com`), `eu` (`https://api.cal.eu`), `custom` (uses `calcom_custom_endpoint`) * `calcom_custom_endpoint`: Custom Cal.com API base URL. Only used when `calcom_endpoint` is `custom` (e.g., `https://my-calcom-instance.com`). * `calcom_booking_fields`: Array of custom booking fields for the event. Each field has: * `slug` (required): Field identifier * `type` (required): Field type (e.g., "text", "email", "phone", "select") * `label` (required): Display label * `required`: Whether the field is required (default: `false`) * `options`: Array of options for select fields * `description`: When to offer scheduling ```json theme={null} "tools": [ { "type": "call_transfer", "phone_number": "+1234567890", "description": "Transfer when customer requests human support" }, { "type": "warm_call_transfer", "supervisor_phone": "+1234567891", "outbound_phone_id": 7, "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.", "custom_sip": false, "caller_id_mode": "outbound_number", "hold_music": "hold_music", "hold_music_volume": 80, "hold_message": "Please hold while I connect you with a supervisor.", "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).", "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?", "connected_message": "You are now connected with a supervisor. I'll leave you to it." }, { "type": "collect_keypad", "timeout": 5, "stop_key": "#" }, { "type": "end_call", "description": "End call when customer confirms satisfaction" } ] ``` #### Voice and TTS Settings Whether to enable emotional text-to-speech synthesis Voice stability setting (0-1). Higher = more consistent voice Voice similarity setting (0-1). Higher = closer to original voice Speech speed multiplier (0.7-1.2) LLM temperature setting (0-1). Lower = more deterministic Custom TTS provider ID. Auto-selected based on language if not provided. Use the [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) endpoint to discover available providers. Custom STT provider ID. Auto-selected based on language if not provided. Pipeline mode only. Use the [Get Transcriber Providers](/api-reference/assistants/get-transcriber-providers) endpoint to discover available providers. #### Call Behavior Settings Whether to allow caller interruptions. Cannot be disabled for `multimodal` and `dualplex` modes. Whether to use filler audio during processing (e.g., "um", "let me check"). Only available for `pipeline` mode. Custom filler word profiles per category. If not provided, defaults are set based on the assistant's language. Each category is an array of short phrases. * `positive`: Filler words for positive/affirmative responses (e.g., "Great!", "Perfect!") * `negative`: Filler words for negative/neutral responses (e.g., "Hmm.", "Mhm.") * `question`: Filler words when processing a question (e.g., "Hmm.", "Let me think.") * `neutral`: Filler words for neutral acknowledgments (e.g., "Ok.", "I understand.") ```json theme={null} "filler_config": { "positive": ["Super!", "Great!", "Perfect!"], "negative": ["Hmm.", "Mhm.", "I see."], "question": ["Hmm.", "Let me check.", "Good question."], "neutral": ["Ok.", "I understand.", "Noted."] } ``` Whether to record the call Whether to enable noise cancellation If true, the assistant waits for the customer to speak first #### Timing Settings Maximum call duration in seconds (20-1200) Maximum silence duration before re-engagement in seconds (1-360) Maximum silence at call start before ending (1-120 seconds). Optional. Maximum ringing time before giving up (1-60 seconds) #### Re-engagement Settings Re-engagement interval in seconds (7-600) Custom prompt for re-engagement messages (max 1000 characters) Example: `"Are you still there? Do you have any other questions?"` #### Voicemail Settings Whether to end call when voicemail is detected Message to leave on voicemail before hanging up (max 1000 characters) #### Endpoint Detection Voice activity detection type. Options: `vad`, `ai` Endpoint sensitivity level (0-5) Interrupt sensitivity level (0-5) Minimum words before interruption is allowed (0-10). Set to enable. #### Ambient Sound Background ambient sound. Options: `off`, `office`, `city`, `forest`, `crowded_room`, `cafe`, `nature` Ambient sound volume level (0-1) #### Webhook Configuration Whether webhook notifications are enabled The webhook URL for post-call notifications. **Required if `is_webhook_active` is true.** Whether to send webhooks only on completed calls (not failed/no-answer) Whether to include recording URL in webhook payload #### Post-Call Evaluation Whether to enable AI post-call evaluation Schema definition for post-call data extraction Field name (3-16 chars, lowercase, alphanumeric and underscores only) Data type. Options: `string`, `number`, `bool` Description of what this field represents (3-255 characters) ```json theme={null} "post_call_schema": [ {"name": "status", "type": "bool", "description": "Was the call objective achieved"}, {"name": "summary", "type": "string", "description": "Brief summary of the call"} ] ``` #### Variables Key-value pairs of custom variables accessible in prompts via `{{variable_name}}` ```json theme={null} "variables": { "company_name": "Acme Corp", "product": "Premium Widget", "support_email": "support@acme.com" } ``` #### Conversation Ended Settings Minutes of chat inactivity before the conversation is considered ended (1-1440) Whether to allow re-triggering the conversation after it ends due to inactivity Webhook URL called when a chat conversation ends due to inactivity. Separate from the main call webhook. *** ## Example Requests ### Pipeline Mode Assistant ```json theme={null} { "name": "Sales Assistant", "voice_id": 1, "language_id": 1, "type": "outbound", "mode": "pipeline", "timezone": "Europe/Bucharest", "initial_message": "Hello! How can I help you today?", "system_prompt": "You are a professional sales assistant...", "llm_model_id": 2, "secondary_language_ids": [2, 3], "knowledgebase_id": 1, "knowledgebase_mode": "prompt", "fillers": true, "filler_config": { "positive": ["Great!", "Perfect!", "Awesome!"], "negative": ["Hmm.", "I see."], "question": ["Good question.", "Let me check."], "neutral": ["Ok.", "Noted.", "I understand."] }, "tool_ids": [1, 5], "tools": [ { "type": "end_call", "description": "End call when customer is satisfied" }, { "type": "call_transfer", "phone_number": "+1234567890", "description": "Transfer to support" }, { "type": "warm_call_transfer", "supervisor_phone": "+1234567891", "outbound_phone_id": 7, "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.", "custom_sip": false, "caller_id_mode": "outbound_number", "hold_music": "hold_music", "hold_music_volume": 80, "hold_message": "Please hold while I connect you with a supervisor.", "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).", "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?", "connected_message": "You are now connected with a supervisor. I'll leave you to it." }, { "type": "collect_keypad", "timeout": 5, "stop_key": "#" } ], "reengagement_interval": 20, "reengagement_prompt": "Are you still there?" } ``` ### Multimodal Mode Assistant ```json theme={null} { "name": "Support Bot", "voice_id": 41, "language_id": 1, "type": "inbound", "mode": "multimodal", "timezone": "America/New_York", "initial_message": "Hi! Welcome to support.", "system_prompt": "You are a helpful support agent...", "multimodal_model_id": 1, "chat_llm_fallback_id": 2, "turn_detection_threshold": 0.7, "knowledgebase_id": 1, "knowledgebase_mode": "function_call", "tts_emotion_enabled": false } ``` ### Dualplex Mode Assistant ```json theme={null} { "name": "Premium Agent", "voice_id": 1, "language_id": 2, "type": "outbound", "mode": "dualplex", "timezone": "Europe/Bucharest", "initial_message": "Buna ziua!", "system_prompt": "Esti un asistent profesionist...", "multimodal_model_id": 4, "chat_llm_fallback_id": 2, "secondary_language_ids": [1, 3], "knowledgebase_id": 1, "knowledgebase_mode": "function_call", "ambient_sound": "office", "ambient_sound_volume": 0.3 } ``` *** ## Response Success message confirming assistant creation The unique identifier of the created assistant The name of the assistant The current status (`inactive` for new assistants) The type (`inbound` or `outbound`) The engine mode (`pipeline`, `multimodal`, or `dualplex`) ```json 201 Success Response theme={null} { "message": "Assistant created successfully", "data": { "id": 789, "name": "Sales Assistant", "status": "inactive", "type": "outbound", "mode": "pipeline" } } ``` ```json 422 Validation Error theme={null} { "message": "Validation failed", "errors": { "name": ["The name field is required."], "voice_id": ["The selected voice is not compatible with the chosen engine type."], "knowledgebase_mode": ["Only function_call mode is available for multimodal assistants."] } } ``` *** ## Notes * All required fields must be provided for successful assistant creation * Use the Get Voices endpoint with `mode` parameter to get compatible voices * For multimodal/dualplex modes, `knowledgebase_mode` must be `function_call` * For multimodal/dualplex modes, `allow_interruptions` is always enabled * Fillers are only available in pipeline mode * The assistant is created with `inactive` status by default # Delete assistant Source: https://docs.repforce.ai/api-reference/assistants/delete-assistant DELETE /user/assistant/{id} Delete a specific AI assistant This endpoint allows you to permanently delete an AI assistant that belongs to the authenticated user. ### Path Parameters The unique identifier of the assistant to delete ### Response Confirmation message indicating the assistant was deleted successfully ### Error Responses Error message when the assistant is not found or doesn't belong to the authenticated user Error message indicating assistant deletion failure ```json 200 Success Response theme={null} { "message": "Assistant deleted successfully" } ``` ```json 404 Not Found theme={null} { "message": "Assistant not found" } ``` ```json 500 Internal Server Error theme={null} { "message": "Assistant deletion failed" } ``` ### Notes * Only assistants that belong to the authenticated user can be deleted * Once an assistant is deleted, it cannot be recovered * This action will permanently remove the assistant and all its configuration * If the assistant is currently handling active calls, those calls may be affected # Disable conversation ended webhook Source: https://docs.repforce.ai/api-reference/assistants/disable-conversation-ended-webhook POST /user/assistants/disable-conversation-ended-webhook Disable conversation ended webhook notifications for an assistant This endpoint disables conversation ended webhook notifications for an assistant, stopping the delivery of updates when chat conversations end. ### Request Body The ID of the assistant to disable the conversation ended webhook for ### Response Success message confirming webhook was disabled Empty array (reserved for future use) ### Error Responses Error message when the assistant is not found or doesn't belong to the authenticated user Error message indicating validation failure Detailed validation errors for each field ```json 200 Success Response theme={null} { "message": "Conversation ended webhook disabled successfully", "data": [] } ``` ```json 404 Not Found theme={null} { "message": "Assistant not found" } ``` ```json 422 Validation Error theme={null} { "message": "The given data was invalid.", "errors": { "assistant_id": [ "The assistant id field is required." ] } } ``` # Disable assistant inbound webhook Source: https://docs.repforce.ai/api-reference/assistants/disable-inbound-webhook POST /user/assistants/disable-inbound-webhook Disable inbound webhook notifications for a specific assistant This endpoint disables inbound webhook notifications for an assistant, stopping the delivery of real-time updates about inbound call completions and data. ### Request Body The ID of the assistant to disable webhook for ### Response Success message confirming webhook was disabled Empty array (reserved for future use) ### Error Responses Error message when the assistant is not found or doesn't belong to the authenticated user Error message indicating validation failure Detailed validation errors for each field ```json 200 Success Response theme={null} { "message": "Inbound webhook disabled successfully", "data": [] } ``` ```json 404 Not Found theme={null} { "message": "Assistant not found" } ``` ```json 422 Validation Error theme={null} { "message": "The given data was invalid.", "errors": { "assistant_id": [ "The assistant id field is required." ] } } ``` # Disable assistant webhook Source: https://docs.repforce.ai/api-reference/assistants/disable-webhook POST /user/assistants/disable-webhook Disable webhook notifications for a specific assistant This endpoint disables webhook notifications for an assistant, stopping all real-time updates about call completions and data. ### Request Body The ID of the assistant to disable webhook for ### Response Success message confirming webhook was disabled Empty array (reserved for future use) ### Error Responses Error message when the assistant is not found or doesn't belong to the authenticated user Error message indicating validation failure Detailed validation errors for each field ```json 200 Success Response theme={null} { "message": "Webhook disabled successfully", "data": [] } ``` ```json 404 Not Found theme={null} { "message": "Assistant not found" } ``` ```json 422 Validation Error theme={null} { "message": "The given data was invalid.", "errors": { "assistant_id": [ "The assistant id field is required." ] } } ``` ### Webhook Behavior When webhook is disabled: * The assistant will stop sending HTTP POST requests to your webhook URL * Both `is_webhook_active` is set to `false` and `webhook_url` is set to `null` * Any ongoing calls will complete normally, but no webhook notifications will be sent * Call data will still be available through the API calls endpoints ### Notes * The assistant must belong to the authenticated user * This completely removes the webhook configuration from the assistant * You can later re-enable webhooks using the enable webhook endpoint with a new URL * Disabling webhooks does not affect call recording or data collection # Enable conversation ended webhook Source: https://docs.repforce.ai/api-reference/assistants/enable-conversation-ended-webhook POST /user/assistants/enable-conversation-ended-webhook Enable webhook notifications when a chat conversation ends This endpoint enables conversation ended webhook notifications for an assistant, allowing you to receive real-time updates when a chat conversation (WhatsApp or Web Widget) ends. The webhook includes the full transcript, extracted variables, and customer information. ### Request Body The ID of the assistant to enable the conversation ended webhook for The URL where webhook notifications will be sent when a conversation ends ### Response Success message confirming webhook was enabled Empty array (reserved for future use) ### Error Responses Error message when the assistant is not found or doesn't belong to the authenticated user Error message indicating validation failure Detailed validation errors for each field ```json 200 Success Response theme={null} { "message": "Conversation ended webhook enabled successfully", "data": [] } ``` ```json 404 Not Found theme={null} { "message": "Assistant not found" } ``` ```json 422 Validation Error theme={null} { "message": "The given data was invalid.", "errors": { "assistant_id": [ "The assistant id field is required." ], "webhook_url": [ "The webhook url field is required." ] } } ``` # Enable assistant inbound webhook Source: https://docs.repforce.ai/api-reference/assistants/enable-inbound-webhook POST /user/assistants/enable-inbound-webhook Enable inbound webhook notifications for a specific assistant This endpoint enables inbound webhook notifications for an assistant, allowing you to receive real-time updates about inbound call completions and data. ### Request Body The ID of the assistant to enable webhook for The URL where webhook notifications will be sent ### Response Success message confirming webhook was enabled Empty array (reserved for future use) ### Error Responses Error message when the assistant is not found or doesn't belong to the authenticated user Error message indicating validation failure Detailed validation errors for each field ```json 200 Success Response theme={null} { "message": "Webhook enabled successfully", "data": [] } ``` ```json 404 Not Found theme={null} { "message": "Assistant not found" } ``` ```json 422 Validation Error theme={null} { "message": "The given data was invalid.", "errors": { "assistant_id": [ "The assistant id field is required." ], "webhook_url": [ "The webhook url field is required." ] } } ``` # List assistants Source: https://docs.repforce.ai/api-reference/assistants/get-assistants GET /user/assistants/get List all assistants for the authenticated user with pagination This endpoint allows you to retrieve all AI assistants belonging to the authenticated user. ### Query Parameters Number of assistants per page (1-100, default: 10) Page number (default: 1) ### Response fields The unique identifier of the assistant The ID of the user who owns this assistant The ID of the phone number assigned to the assistant Engine ID Synthesizer ID Transcriber ID The ID of the voice used by the assistant The instance ID for the assistant The name of the assistant Custom variables defined for the assistant Whether post-call evaluation is enabled Whether filler audio is enabled (1 = enabled, 0 = disabled) Schema definition for post-call data extraction The name of the schema field The data type (string, number, bool) Description of what this field represents Array of tools available to the assistant Whether webhook notifications are enabled The webhook URL for post-call notifications The webhook URL for inbound call notifications Language The type of assistant (inbound or outbound) The current status of the assistant (active or inactive) Maximum call duration in seconds Whether to record calls The initial message the assistant will speak The system prompt that defines the assistant's behavior ID for flows platform integration The timezone setting for the assistant The date and time when the assistant was created The date and time when the assistant was last updated Maximum silence duration in seconds before re-engagement Re-engagement interval in seconds Soft deletion timestamp (null if not deleted) Whether to end call when voicemail is detected (1 = yes, 0 = no) LLM temperature setting as string Voice stability setting as string Voice similarity setting as string Whether to allow caller interruptions Whether noise cancellation is enabled Endpoint sensitivity level Speech speed multiplier as string Voice activity detection type (vad or ai) Whether to wait for customer to speak first The engine mode (pipeline or multimodal) The ID of the language used by the assistant ID of the transcriber provider ID of the synthesizer provider ID of the LLM model used ID of the multimodal model used Ambient sound setting Unique UUID for the assistant Whether to send webhooks only on completed calls Whether to include recording URL in webhook payload Interrupt sensitivity level Configuration for filler audio responses Array of neutral filler responses Array of negative filler responses Array of positive filler responses Array of question filler responses ID of the associated knowledge base Knowledge base mode setting Minimum number of words before interruption is allowed Ambient sound volume level as string Settings for web widget integration The current page number Number of items per page Total number of assistants The last page number ```json 200 Response theme={null} { "current_page": 1, "data": [ { "id": 127, "user_id": 1, "phone_number_id": 45, "engine_id": null, "synthesizer_id": null, "transcriber_id": null, "voice_id": 8, "instance_id": 1, "name": "Sales Outreach Assistant", "variables": { "company_name": "Your Company", "product_line": "Premium Services", "rep_name": "Assistant" }, "post_call_evaluation": true, "fillers": 1, "post_call_schema": [ { "name": "interest_level", "type": "string", "description": "Customer's level of interest (high, medium, low)" }, { "name": "budget_qualified", "type": "bool", "description": "Whether the prospect has adequate budget" }, { "name": "follow_up_date", "type": "string", "description": "Preferred date for follow-up contact" } ], "tools": [], "is_webhook_active": true, "webhook_url": "https://yourcompany.com/api/webhooks/sales-calls", "inbound_webhook_url": null, "language": null, "type": "outbound", "status": "active", "max_duration": 900, "record": true, "initial_message": "Hi, this is an assistant from Your Company. I hope I'm catching you at a good time. How are you doing today?", "system_prompt": "You are a sales representative for Your Company. Be professional, friendly, and focus on qualifying leads for premium services.", "flows_platform_id": null, "timezone": "America/Los_Angeles", "created_at": "2025-07-15T14:32:15.000000Z", "updated_at": "2025-08-02T09:18:42.000000Z", "max_silence_duration": 25, "reengagement_interval": 45, "deleted_at": null, "end_call_on_voicemail": 1, "llm_temperature": "0.35", "voice_stability": "0.75", "voice_similarity": "0.85", "allow_interruptions": true, "enable_noise_cancellation": true, "endpoint_sensitivity": 1.8, "speech_speed": "1.10", "endpoint_type": "vad", "wait_for_customer": true, "mode": "pipeline", "language_id": 1, "transcriber_provider_id": null, "synthesizer_provider_id": null, "llm_model_id": 3, "multimodal_model_id": null, "ambient_sound": "office", "uuid": "a7b3c942-5f1e-4d28-8c59-2e4f7a8b9c3d", "send_webhook_only_on_completed": true, "include_recording_in_webhook": true, "interrupt_sensitivity": 1.2, "filler_config": { "neutral": [ "I see.", "Understood.", "Right.", "Got it.", "Okay." ], "negative": [ "I understand.", "Hmm.", "I see.", "Okay." ], "positive": [ "Excellent!", "That's great!", "Wonderful!", "Perfect!" ], "question": [ "Let me think...", "Good question.", "Hmm.", "Right." ] }, "knowledgebase_id": 12, "knowledgebase_mode": "hybrid", "min_interrupt_words": 3, "ambient_sound_volume": "0.30", "widget_settings": { "theme": "modern", "color": "#2563eb", "position": "bottom-right" } } ], "first_page_url": "https://app.repforce.ai/api/user/assistants/get?page=1", "from": 1, "last_page": 5, "last_page_url": "https://app.repforce.ai/api/user/assistants/get?page=5", "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://app.repforce.ai/api/user/assistants/get?page=1", "label": "1", "active": true }, { "url": "https://app.repforce.ai/api/user/assistants/get?page=2", "label": "2", "active": false } ], "next_page_url": "https://app.repforce.ai/api/user/assistants/get?page=2", "path": "https://app.repforce.ai/api/user/assistants/get", "per_page": 10, "prev_page_url": null, "to": 10, "total": 47 } ``` # Get available languages Source: https://docs.repforce.ai/api-reference/assistants/get-languages GET /user/assistants/languages Retrieve all available languages for assistant configuration This endpoint returns a list of all available languages that can be used when creating or updating assistants. ### Response fields The unique identifier of the language The display name of the language The ISO 639-1 two-letter language code ```json 200 Response theme={null} [ { "id": 1, "name": "English", "iso_2": "en" }, { "id": 2, "name": "Romanian", "iso_2": "ro" }, { "id": 3, "name": "French", "iso_2": "fr" }, { "id": 4, "name": "Spanish", "iso_2": "es" }, { "id": 5, "name": "German", "iso_2": "de" } ] ``` ### Notes * Use the `id` field as `language_id` when creating or updating assistants * Use the `id` field in `secondary_language_ids` array for multi-language assistants * The `iso_2` code can be useful for language-specific functionality * All available languages are returned in a single request # Get available models Source: https://docs.repforce.ai/api-reference/assistants/get-models GET /user/assistants/models Retrieve available AI models for assistant configuration This endpoint returns a list of available AI models that can be used when creating or updating assistants. ### Query Parameters The type of models to retrieve based on engine mode: * `llm` - LLM models for **pipeline** mode (default) * `multimodal` - Multimodal models for **multimodal** mode * `dualplex` - Multimodal models for **dualplex** mode ### Response fields The unique identifier of the model The display name of the model The internal code (only for multimodal/dualplex models) ```json LLM Models (type=llm) theme={null} [ { "id": 1, "name": "GPT-4o-mini" }, { "id": 2, "name": "GPT-4.1-mini" } ] ``` ```json Multimodal/Dualplex Models (type=multimodal or type=dualplex) theme={null} [ { "id": 1, "name": "GPT-4o", "code": "gpt-4o-realtime" }, { "id": 4, "name": "GPT Realtime", "code": "gpt-realtime" } ] ``` ### Notes * If no `type` parameter is provided, LLM models are returned by default * Use `llm_model_id` field when creating **pipeline** assistants * Use `multimodal_model_id` field when creating **multimodal** or **dualplex** assistants # Get outbound assistants Source: https://docs.repforce.ai/api-reference/assistants/get-outbound-assistants GET /user/assistants/outbound Retrieve all outbound assistants for the authenticated user This endpoint returns a list of all outbound assistants belonging to the authenticated user. Outbound assistants are used for making calls to leads and prospects. ### Response fields The unique identifier of the assistant The ID of the user who owns this assistant The name of the assistant The type of assistant (will always be "outbound" for this endpoint) The engine mode (`pipeline` or `multimodal`) The current status of the assistant The ID of the voice used by the assistant The ID of the language used by the assistant The timezone setting for the assistant The initial message the assistant will speak The system prompt that defines the assistant's behavior Custom variables defined for the assistant The webhook URL for post-call notifications Whether webhook notifications are enabled The date and time when the assistant was created The date and time when the assistant was last updated ```json 200 Response theme={null} [ { "id": 123, "user_id": 1, "name": "Sales Outbound Assistant", "type": "outbound", "mode": "pipeline", "status": "active", "voice_id": 8, "language_id": 1, "timezone": "America/New_York", "initial_message": "Hi, this is Sarah from Your Company. I hope I'm catching you at a good time. How are you doing today?", "system_prompt": "You are a sales representative for Your Company. Be professional, friendly, and focus on qualifying leads.", "variables": { "company_name": "Your Company", "product_line": "Premium Services" }, "webhook_url": "https://yourcompany.com/api/webhooks/outbound-calls", "is_webhook_active": true, "created_at": "2025-07-15T14:32:15.000000Z", "updated_at": "2025-08-02T09:18:42.000000Z" }, { "id": 124, "user_id": 1, "name": "Follow-up Assistant", "type": "outbound", "mode": "multimodal", "status": "inactive", "voice_id": 12, "language_id": 1, "timezone": "America/Los_Angeles", "initial_message": "Hello! I'm calling to follow up on our previous conversation. Do you have a few minutes to chat?", "system_prompt": "You are a follow-up specialist. Be warm and professional while gathering feedback and next steps.", "variables": { "purpose": "follow_up", "max_duration": "5_minutes" }, "webhook_url": null, "is_webhook_active": false, "created_at": "2025-07-20T10:15:30.000000Z", "updated_at": "2025-07-25T16:45:22.000000Z" } ] ``` ### Notes * This endpoint only returns assistants with type "outbound" * All assistants belonging to the authenticated user are returned (no pagination) * Use these assistants with the make call endpoint to initiate outbound calls * Outbound assistants can be used for sales calls, follow-ups, surveys, and other proactive calling scenarios # Get available phone numbers Source: https://docs.repforce.ai/api-reference/assistants/get-phone-numbers GET /user/assistants/phone-numbers Retrieve all available phone numbers for assistant assignment This endpoint returns a list of phone numbers owned by the authenticated user that can be assigned to assistants, with optional filtering by assistant type. ### Query Parameters Filter phone numbers by assistant type. Options: `inbound`, `outbound` ### Response fields The unique identifier of the phone number The phone number in E.164 format The country code for the phone number The human-readable type label for the phone number Whether the phone number is available for assignment (not currently assigned to an inbound assistant) ```json 200 Response theme={null} [ { "id": 45, "phone_number": "+1234567890", "country_code": "US", "type_label": "Normal", "is_available": true }, { "id": 46, "phone_number": "+1234567891", "country_code": "US", "type_label": "SIP", "is_available": false }, { "id": 47, "phone_number": "+441234567890", "country_code": "GB", "type_label": "Caller ID", "is_available": true } ] ``` ### Notes * Only phone numbers owned by the authenticated user are returned * When `type=inbound` is specified, caller ID numbers and already assigned numbers are filtered out * The `is_available` field indicates if the number can be assigned to a new inbound assistant * Phone numbers are returned in the values collection format (indexed array) * Use the `id` field when assigning phone numbers to assistants # Get synthesizer providers Source: https://docs.repforce.ai/api-reference/assistants/get-synthesizer-providers GET /user/assistants/synthesizer-providers Retrieve available TTS (text-to-speech) synthesizer providers This endpoint returns a list of available synthesizer providers that can be used when creating or updating assistants. Use the returned `id` as `synthesizer_provider_id` when configuring an assistant. ### Query Parameters Filter providers by language support. Only returns providers that support the given language. Use the [Get Languages](/api-reference/assistants/get-languages) endpoint to get available language IDs. ### Response fields The unique identifier of the provider. Use this as `synthesizer_provider_id` when creating or updating assistants. The display name of the provider (e.g., "ElevenLabs", "Azure", "Cartesia") The internal code of the provider ```json 200 Response theme={null} [ { "id": 1, "name": "ElevenLabs", "code": "elevenlabs" }, { "id": 2, "name": "Azure", "code": "azure" }, { "id": 3, "name": "Cartesia", "code": "cartesia" } ] ``` ```json 200 Filtered by language theme={null} [ { "id": 1, "name": "ElevenLabs", "code": "elevenlabs" }, { "id": 3, "name": "Cartesia", "code": "cartesia" } ] ``` ### Notes * If no `language_id` filter is provided, all providers are returned * Not all providers support all languages — use the `language_id` filter to get compatible providers * Synthesizer providers are only relevant for `pipeline` and `dualplex` modes (multimodal mode handles TTS internally) * If you don't set `synthesizer_provider_id` when creating an assistant, the language's default provider is used # Get transcriber providers Source: https://docs.repforce.ai/api-reference/assistants/get-transcriber-providers GET /user/assistants/transcriber-providers Retrieve available STT (speech-to-text) transcriber providers This endpoint returns a list of available transcriber providers that can be used when creating or updating assistants. Use the returned `id` as `transcriber_provider_id` when configuring an assistant. ### Query Parameters Filter providers by language support. Only returns providers that support the given language. Use the [Get Languages](/api-reference/assistants/get-languages) endpoint to get available language IDs. ### Response fields The unique identifier of the provider. Use this as `transcriber_provider_id` when creating or updating assistants. The display name of the provider (e.g., "Deepgram", "Azure", "Gladia") The internal code of the provider ```json 200 Response theme={null} [ { "id": 1, "name": "Deepgram", "code": "deepgram" }, { "id": 2, "name": "Azure", "code": "azure" }, { "id": 3, "name": "Gladia", "code": "gladia" } ] ``` ### Notes * If no `language_id` filter is provided, all providers are returned * Not all providers support all languages — use the `language_id` filter to get compatible providers * Transcriber providers are only relevant for `pipeline` mode (multimodal and dualplex modes handle STT internally) * If you don't set `transcriber_provider_id` when creating an assistant, the language's default provider is used # Get available voices Source: https://docs.repforce.ai/api-reference/assistants/get-voices GET /user/assistants/voices Retrieve all available voices for assistant configuration This endpoint returns a list of all available voices that can be used when creating or updating assistants, with optional filtering by assistant mode and language. ### Query Parameters Filter voices by assistant mode. Options: `pipeline`, `multimodal`, `dualplex` Filter voices by language ID. Use the [Get Languages](/api-reference/assistants/get-languages) endpoint to get available language IDs. ### Response fields The unique identifier of the voice The display name of the voice The language ID this voice is associated with The gender of the voice (male/female) URL to an audio sample of the voice. Can be used to let users preview voices before selecting one. The accent of the voice (e.g., "American", "British"). May be `null`. The age category of the voice (e.g., "Young", "Middle aged"). May be `null`. The TTS provider ID this voice belongs to. Use the [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) endpoint to resolve provider names. May be `null`. ```json 200 Response theme={null} [ { "id": 1, "name": "Alloy", "language_id": 1, "gender": "female", "preview_url": "https://cdn.openai.com/API/voice-previews/alloy.flac", "accent": null, "age": "Middle aged", "synthesizer_provider_id": null }, { "id": 10, "name": "Zephyr", "language_id": 1, "gender": "female", "preview_url": "https://gstatic.com/aistudio/voices/samples/Zephyr.wav", "accent": null, "age": "Middle aged", "synthesizer_provider_id": 1 }, { "id": 11, "name": "Puck", "language_id": 1, "gender": "male", "preview_url": "https://gstatic.com/aistudio/voices/samples/Puck.wav", "accent": null, "age": "Middle aged", "synthesizer_provider_id": 1 } ] ``` ### Notes * Use the `id` field as `voice_id` when creating or updating assistants * Filter by `mode` to get only voices compatible with your intended assistant type * Filter by `language_id` to get voices for a specific language * If no filters are provided, all available voices are returned * Only voices that are public or belong to the authenticated user are returned # Update assistant Source: https://docs.repforce.ai/api-reference/assistants/update-assistant PUT /user/assistant/{id} Update an existing AI assistant's configuration This endpoint allows you to update an existing AI assistant's configuration. All fields are optional - only provide the fields you want to update. ### Path Parameters The unique identifier of the assistant to update ### Request Body #### Core Fields The name of the assistant (max 255 characters) The voice ID to use for the assistant. Use the [Get Voices](/api-reference/assistants/get-voices) endpoint with the `mode` parameter to get compatible voices for your engine mode. The language ID for the assistant. Use the [Get Languages](/api-reference/assistants/get-languages) endpoint to get available languages. The assistant type. Options: `inbound`, `outbound` The engine mode. Options: `pipeline`, `multimodal`, `dualplex` Changing the mode will reset mode-specific settings to defaults for the new mode. The timezone for the assistant (e.g., "Europe/Bucharest", "America/New\_York") The initial message the assistant will speak when the call starts (max 200 characters) The system prompt that defines the assistant's behavior and personality #### Mode-Specific Fields The LLM model ID to use. Only applies to `pipeline` mode. Use the [Get Models](/api-reference/assistants/get-models) endpoint to get available models. The multimodal model ID. Only applies to `multimodal` and `dualplex` modes. Use the [Get Models](/api-reference/assistants/get-models) endpoint to get available multimodal models. Fallback LLM model ID for tool calls in multimodal/dualplex modes. Set to `null` to remove. Turn detection sensitivity for multimodal/dualplex modes (0-1). Set to `null` for auto. #### Secondary Languages Array of additional language IDs the assistant can speak. Replaces existing secondary languages. Pass an empty array `[]` to remove all secondary languages. ```json theme={null} "secondary_language_ids": [2, 3, 4] ``` #### Knowledgebase Settings The knowledgebase ID to attach. Set to `null` to remove knowledgebase. How to use the knowledgebase. Options: * `function_call` - AI calls a function to search (required for multimodal/dualplex) * `prompt` - Knowledge is injected into prompt (pipeline only) #### Phone Number The ID of a phone number to assign. Set to `null` to unassign. Must belong to your account. For `inbound` assistants, the phone number cannot be a Caller ID type and cannot be already assigned to another inbound assistant. #### Custom Mid-Call Tools Array of custom mid-call tool IDs to sync. **Replaces all existing tool assignments.** Pass an empty array `[]` to remove all tools. Each tool must belong to your account. ```json theme={null} "tool_ids": [1, 5, 12] ``` #### Built-in Tools Array of built-in tools. **Replaces all existing built-in tools.** Pass an empty array `[]` to remove all tools. **call\_transfer** - Transfer the call to another phone number * `phone_number` (required): Phone number to transfer to * `description`: When to transfer the call * `custom`: If true, AI can determine transfer number dynamically * `timezone`: Timezone for transfer availability * `warm_transfer`: Send a message to the customer before transferring (default: `false`) * `warm_transfer_message`: Prompt telling the AI what to say before transferring (e.g., "Tell the customer that the call is being transferred.") **warm\_call\_transfer** - Warm transfer with supervisor briefing * `supervisor_phone` (required): Phone number to dial for the warm transfer (e.g., "+14155552001"). If `custom_sip` is enabled, this is a SIP address or internal extension instead. * `outbound_phone_id` (required): ID of the phone number used to dial the supervisor. * `description` (required): **When to transfer** — describes when the AI should initiate the warm transfer (e.g., "Transfer the call to a human supervisor when the customer requests to speak with a real person.") * `custom_sip`: Enable to enter a custom SIP address or internal extension instead of a phone number (default: `false`) * `caller_id_mode`: What phone number the supervisor sees when receiving the call. Options: `outbound_number` (default — shows the outbound phone number), `customer_number` (shows the caller's number), `custom` (shows a custom number) * `custom_caller_id`: Custom phone number shown to supervisor. Only used when `caller_id_mode` is `custom`. * `hold_music`: Audio played to the caller while on hold. Options: `hold_music` (default — plays default hold music), `none` (silence, no music) * `hold_music_volume`: Volume level for hold music, 0-100 (default: `80`) * `hold_message`: Message spoken to caller before placing them on hold (default: "Please hold while I connect you with a supervisor.") * `summary_instructions`: Instructions for how the AI should brief the supervisor about the call (default: "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).") * `briefing_initial_message`: The first message the AI says to the supervisor when they answer (default: "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?") * `connected_message`: Message spoken to caller after supervisor is connected (default: "You are now connected with a supervisor. I'll leave you to it.") **end\_call** - End the call programmatically * `description`: When the AI should end the call **dtmf\_input** - Send DTMF tones (keypad input) * `description`: When to use DTMF input (for IVR navigation) **collect\_keypad** - Collect keypad input from the caller * `timeout`: Seconds to wait for input, 1-30 (default: 5) * `stop_key`: Key that ends input. Options: `#` (default), `*` **calendar\_integration** - Schedule appointments via Cal.com * `calcom_api_key` (required): Your Cal.com API key * `calcom_event_slug` (required): The event type slug from Cal.com * `calcom_team_slug`: Team slug if the event belongs to a Cal.com team * `calcom_endpoint`: Cal.com API region. Options: `us` (default — `https://api.cal.com`), `eu` (`https://api.cal.eu`), `custom` (uses `calcom_custom_endpoint`) * `calcom_custom_endpoint`: Custom Cal.com API base URL. Only used when `calcom_endpoint` is `custom` (e.g., `https://my-calcom-instance.com`). * `calcom_booking_fields`: Array of custom booking fields for the event. Each field has: * `slug` (required): Field identifier * `type` (required): Field type (e.g., "text", "email", "phone", "select") * `label` (required): Display label * `required`: Whether the field is required (default: `false`) * `options`: Array of options for select fields * `description`: When to offer scheduling ```json theme={null} "tools": [ { "type": "dtmf_input", "description": "Navigate IVR when needed" }, { "type": "warm_call_transfer", "supervisor_phone": "+1234567890", "outbound_phone_id": 7, "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.", "custom_sip": false, "caller_id_mode": "outbound_number", "hold_music": "hold_music", "hold_music_volume": 80, "hold_message": "Please hold while I connect you with a supervisor.", "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).", "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?", "connected_message": "You are now connected with a supervisor. I'll leave you to it." }, { "type": "collect_keypad", "timeout": 5, "stop_key": "#" }, { "type": "end_call", "description": "End call when done" } ] ``` #### Voice and TTS Settings Whether to enable emotional text-to-speech synthesis Voice stability setting (0-1). Higher = more consistent voice Voice similarity setting (0-1). Higher = closer to original voice Speech speed multiplier (0.7-1.2) LLM temperature setting (0-1). Lower = more deterministic Custom TTS provider ID. Set to `null` to use language default. Use the [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) endpoint to discover available providers. Custom STT provider ID. Pipeline mode only. Set to `null` to use language default. Use the [Get Transcriber Providers](/api-reference/assistants/get-transcriber-providers) endpoint to discover available providers. #### Call Behavior Settings Whether to allow caller interruptions. Cannot be disabled for `multimodal` and `dualplex` modes. Whether to use filler audio during processing. Only available for `pipeline` mode. Custom filler word profiles per category. Replaces existing filler config. Each category is an array of short phrases. * `positive`: Filler words for positive/affirmative responses * `negative`: Filler words for negative/neutral responses * `question`: Filler words when processing a question * `neutral`: Filler words for neutral acknowledgments ```json theme={null} "filler_config": { "positive": ["Great!", "Perfect!"], "negative": ["Hmm.", "I see."], "question": ["Good question.", "Let me check."], "neutral": ["Ok.", "Noted."] } ``` Whether to record the call Whether to enable noise cancellation If true, the assistant waits for the customer to speak first #### Timing Settings Maximum call duration in seconds (20-1200) Maximum silence duration before re-engagement in seconds (1-360) Maximum silence at call start before ending (1-120 seconds). Set to `null` to disable. Maximum ringing time before giving up (1-60 seconds) #### Re-engagement Settings Re-engagement interval in seconds (7-600) Custom prompt for re-engagement messages (max 1000 characters). Set to `null` to use default. #### Voicemail Settings Whether to end call when voicemail is detected Message to leave on voicemail before hanging up (max 1000 characters). Set to `null` to disable. #### Endpoint Detection Voice activity detection type. Options: `vad`, `ai` Endpoint sensitivity level (0-5) Interrupt sensitivity level (0-5) Minimum words before interruption is allowed (0-10). Set to `null` to disable. #### Ambient Sound Background ambient sound. Options: `off`, `office`, `city`, `forest`, `crowded_room`, `cafe`, `nature` Ambient sound volume level (0-1) #### Webhook Configuration Whether webhook notifications are enabled The webhook URL for post-call notifications. Set to `null` to remove. Whether to send webhooks only on completed calls (not failed/no-answer) Whether to include recording URL in webhook payload #### Post-Call Evaluation Whether to enable AI post-call evaluation Schema definition for post-call data extraction. Replaces existing schema. Field name (3-16 chars, lowercase, alphanumeric and underscores only) Data type. Options: `string`, `number`, `bool` Description of what this field represents (3-255 characters) #### Variables Key-value pairs of custom variables. **Replaces all existing variables.** ```json theme={null} "variables": { "company_name": "Acme Corp", "product": "Premium Widget" } ``` #### Conversation Ended Settings Minutes of chat inactivity before the conversation is considered ended (1-1440). Set to `null` to disable. Default: `30` Whether to allow re-triggering the conversation after it ends due to inactivity Webhook URL called when a chat conversation ends due to inactivity. Set to `null` to remove. Separate from the main call webhook. *** ## Example Requests ### Update Basic Settings ```json theme={null} { "name": "Updated Assistant Name", "initial_message": "Hello! How may I assist you?", "max_duration": 900 } ``` ### Switch to Multimodal Mode ```json theme={null} { "mode": "multimodal", "voice_id": 41, "multimodal_model_id": 1, "chat_llm_fallback_id": 2, "knowledgebase_mode": "function_call" } ``` ### Update Tools and Knowledgebase ```json theme={null} { "tool_ids": [1, 5, 12], "knowledgebase_id": 3, "knowledgebase_mode": "prompt" } ``` ### Update Re-engagement and Voicemail ```json theme={null} { "reengagement_interval": 15, "reengagement_prompt": "Are you still there? I'm here to help.", "end_call_on_voicemail": true, "voice_mail_message": "Hello, please call us back at your convenience." } ``` ### Remove Optional Settings ```json theme={null} { "phone_number_id": null, "webhook_url": null, "tool_ids": [], "secondary_language_ids": [] } ``` *** ## Response Success message confirming assistant update The unique identifier of the updated assistant The name of the assistant The current status of the assistant The type (`inbound` or `outbound`) The engine mode (`pipeline`, `multimodal`, or `dualplex`) ```json 200 Success Response theme={null} { "message": "Assistant updated successfully", "data": { "id": 789, "name": "Updated Sales Assistant", "status": "active", "type": "outbound", "mode": "pipeline" } } ``` ```json 404 Not Found theme={null} { "message": "Assistant not found" } ``` ```json 422 Validation Error theme={null} { "message": "Validation failed", "errors": { "speech_speed": ["The speech speed must be between 0.7 and 1.2."], "voice_id": ["The selected voice is not compatible with the chosen engine type."], "allow_interruptions": ["Interruptions cannot be disabled in multimodal or dualplex mode."] } } ``` *** ## Notes * Only the fields you provide in the request body will be updated * To remove optional fields, explicitly set them to `null` * To clear arrays (tools, secondary languages), pass an empty array `[]` * The assistant must belong to the authenticated user * Use the Get Voices endpoint with `mode` parameter to get compatible voices * For multimodal/dualplex modes, `knowledgebase_mode` must be `function_call` * For multimodal/dualplex modes, `allow_interruptions` cannot be disabled * Changing the mode resets mode-specific settings (LLM model, multimodal model, providers) # Authentication Source: https://docs.repforce.ai/api-reference/authentication Learn how to authenticate your API requests The RepForce.ai API uses API keys to authenticate requests. You need to include your API key in the header of each request you make to the API. ## Obtaining an API Key To obtain an API key: 1. Log in to your RepForce.ai account at [https://app.repforce.ai](https://app.repforce.ai) 2. Navigate to the "API Keys" page 3. Click on the "Create new API Key" button 4. Copy your new API key and store it securely Keep your API key confidential and secure. Do not share it publicly or commit it to version control systems. ## Using the API Key Include your API key in the `Authorization` header of each request: ```text theme={null} Authorization: Bearer YOUR_API_KEY ``` Replace `YOUR_API_KEY` with your actual API key. ## Example Request Here's an example of how to include the API key in a cURL request: ```bash theme={null} curl -X GET "https://app.repforce.ai/api/user/campaigns" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Replace `YOUR_API_KEY` with your actual API key when making requests. # Create API key Source: https://docs.repforce.ai/api-reference/authentication/create-api-key POST /user/api-keys Generate a new API key for the authenticated user This endpoint generates a new API key for the authenticated user. Unlike the login endpoint which creates a session token, this creates a persistent API key that can be used for long-term API access. This endpoint requires authentication. Use your existing API key or session token to create additional API keys. ### Request Body A name/label for the API key (e.g., "Production", "Development", "My App") ### Response Success message The created API key details The name/label of the API key The API key token. **Store this securely** - it will only be shown once. ISO 8601 timestamp of when the API key was created ```json 201 Created theme={null} { "message": "API key created successfully.", "api_key": { "name": "Production API Key", "token": "1|abc123xyz789abcdef...", "created_at": "2025-01-08T10:30:00.000000Z" } } ``` ```json 422 Validation Error theme={null} { "message": "The name field is required.", "errors": { "name": ["The name field is required."] } } ``` ### Example Request ```bash theme={null} curl -X POST https://app.repforce.ai/api/user/api-keys \ -H "Authorization: Bearer YOUR_EXISTING_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production API Key" }' ``` The API key token is only returned once. Make sure to store it securely. If you lose it, you'll need to create a new one. ### Managing API Keys * **GET /user/api-keys** - List all API keys for the authenticated user * **DELETE /user/api-keys/** - Delete a specific API key # Delete API key Source: https://docs.repforce.ai/api-reference/authentication/delete-api-key DELETE /user/api-keys/{id} Delete an API key This endpoint permanently deletes an API key. Any applications using this key will immediately lose access. ### Path Parameters The unique identifier of the API key to delete ### Response Success message ```json 200 Response theme={null} { "message": "API key deleted successfully." } ``` ```json 404 Not Found theme={null} { "message": "API key not found." } ``` This action is immediate and cannot be undone. Any applications using this API key will stop working immediately. # List API keys Source: https://docs.repforce.ai/api-reference/authentication/list-api-keys GET /user/api-keys Get all API keys for the authenticated user This endpoint returns a list of all API keys associated with the authenticated user's account. ### Response Array of API key objects The unique identifier of the API key The name/label of the API key ISO 8601 timestamp of when the API key was last used (null if never used) ISO 8601 timestamp of when the API key was created ```json 200 Response theme={null} { "api_keys": [ { "id": 1, "name": "Production API Key", "last_used_at": "2025-01-08T15:30:00.000000Z", "created_at": "2025-01-01T10:00:00.000000Z" }, { "id": 2, "name": "Development API Key", "last_used_at": null, "created_at": "2025-01-05T14:20:00.000000Z" } ] } ``` ```json 200 Empty Response theme={null} { "api_keys": [] } ``` For security reasons, the actual API key tokens are not returned. Only metadata about the keys is shown. # Delete call Source: https://docs.repforce.ai/api-reference/calls/delete-call DELETE /user/calls/{call} Delete a specific call record This endpoint allows you to delete a specific call record that belongs to the authenticated user. ### Path Parameters The unique identifier of the call to delete ### Response Confirmation message indicating the call was deleted successfully ### Error Responses Error message when the call is not found or doesn't belong to the authenticated user ```json 200 Success Response theme={null} { "message": "Call deleted successfully" } ``` ```json 404 Not Found theme={null} { "message": "Call not found" } ``` ### Notes * Only calls that belong to assistants owned by the authenticated user can be deleted * Once a call is deleted, it cannot be recovered * This action will permanently remove the call record, including any associated transcript, recording, and metadata * The call recording file (if exists) will also be deleted from storage # Get call Source: https://docs.repforce.ai/api-reference/calls/get-call GET /user/calls/{id} Retrieve details of a specific call by ID This endpoint allows you to retrieve detailed information about a specific call belonging to the authenticated user. ### Path Parameters The unique identifier of the call ### Response fields The unique identifier of the call The name of the assistant that handled the call The name of the campaign this call belongs to (if applicable) The type of the call (`inbound`, `outbound`, or `web`) The duration of the call in seconds The phone number used by the assistant The phone number of the client The current status of the call The transcript of the call conversation Variables collected during the call Evaluation data for the call performance Response from any configured webhooks The cost charged by the carrier for this call The total cost of the call including all fees Who answered the call (`human`, `machine`, or `unknown`) URL to the call recording (if available and enabled) The date and time when the call was created The date and time when the call was last updated ```json 200 Response theme={null} { "id": 123, "assistant_name": "Sales Assistant", "campaign_name": "Q4 Outreach Campaign", "type": "outbound", "duration": 245, "assistant_phone_number": "+1234567890", "client_phone_number": "+1987654321", "status": "completed", "transcript": "Hello, this is Sarah from RepForce.ai. How are you doing today?...", "variables": { "customer_name": "John Smith", "interest_level": "high", "follow_up_date": "2025-08-15" }, "evaluation": { "sentiment": "positive", "outcome": "qualified_lead", "score": 8.5 }, "webhook_response": { "status": "success", "data": { "crm_contact_id": "abc123" } }, "carrier_cost": 0.02, "total_cost": 0.025, "answered_by": "human", "recording_url": "https://repforce.ai/recordings/calls/123.mp3", "created_at": "2025-08-04 14:30:00", "updated_at": "2025-08-04 14:34:05" } ``` ```json 404 Response theme={null} { "message": "Call not found" } ``` # List calls Source: https://docs.repforce.ai/api-reference/calls/get-calls GET /user/calls List all calls for the authenticated user with filtering options This endpoint allows you to list all calls belonging to the authenticated user with various filtering options. ### Query Parameters Filter calls by status. Possible values: `initiated`, `ringing`, `busy`, `in-progress`, `ended`, `completed`, `ended_by_customer`, `ended_by_assistant`, `no-answer`, `failed` Filter calls by type. Possible values: `inbound`, `outbound`, `web` Filter calls by client phone number Filter calls by assistant ID Filter calls by campaign ID Filter calls from this date (YYYY-MM-DD format) Filter calls until this date (YYYY-MM-DD format) Number of calls per page (1-100, default: 15) Page number (default: 1) ### Response fields The unique identifier of the call The name of the assistant that handled the call The name of the campaign this call belongs to (if applicable) The type of the call (`inbound`, `outbound`, or `web`) The duration of the call in seconds The phone number used by the assistant The phone number of the client The current status of the call The transcript of the call conversation Variables collected during the call Evaluation data for the call performance Response from any configured webhooks The cost charged by the carrier for this call The total cost of the call including all fees Who answered the call (`human`, `machine`, or `unknown`) URL to the call recording (if available and enabled) The date and time when the call was created The date and time when the call was last updated The current page number Number of items per page Total number of calls matching the criteria The last page number ```json 200 Response theme={null} { "current_page": 1, "data": [ { "id": 123, "assistant_name": "Sales Assistant", "campaign_name": "Q4 Outreach Campaign", "type": "outbound", "duration": 245, "assistant_phone_number": "+1234567890", "client_phone_number": "+1987654321", "status": "completed", "transcript": "Hello, this is Sarah from RepForce.ai. How are you doing today?...", "variables": { "customer_name": "John Smith", "interest_level": "high", "follow_up_date": "2025-08-15" }, "evaluation": { "sentiment": "positive", "outcome": "qualified_lead", "score": 8.5 }, "webhook_response": { "status": "success", "data": { "crm_contact_id": "abc123" } }, "carrier_cost": 0.02, "total_cost": 0.025, "answered_by": "human", "recording_url": "https://repforce.ai/recordings/calls/123.mp3", "created_at": "2025-08-04 14:30:00", "updated_at": "2025-08-04 14:34:05" } ], "first_page_url": "https://app.repforce.ai/api/user/calls?page=1", "from": 1, "last_page": 10, "last_page_url": "https://app.repforce.ai/api/user/calls?page=10", "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://app.repforce.ai/api/user/calls?page=1", "label": "1", "active": true }, { "url": "https://app.repforce.ai/api/user/calls?page=2", "label": "2", "active": false } ], "next_page_url": "https://app.repforce.ai/api/user/calls?page=2", "path": "https://app.repforce.ai/api/user/calls", "per_page": 15, "prev_page_url": null, "to": 15, "total": 150 } ``` # Make a phone call Source: https://docs.repforce.ai/api-reference/calls/make-phone-call POST /user/make_call Make a phone call This endpoint allows you to make a phone call. ### Request body The phone number of the customer in E.164 format (e.g. +1234567890) The ID of the assistant to make the call with Custom variables to pass to the call. You can include **any variables that are defined on your assistant** (see [Call variables](/ai-assistants/settings/prompt-and-tools#call-variables)). The examples below are just for illustration — use your own variable names as configured in the assistant settings. e.g. the name of the customer e.g. the email of the customer ### Response The message of the response ```json 200 Response theme={null} { "message": "Call initiated successfully", "data": {} } ``` # Create campaign Source: https://docs.repforce.ai/api-reference/campaigns/create-campaign POST /user/campaign Create a new outbound calling campaign This endpoint allows you to create a new outbound calling campaign with the specified configuration. ### Request body The name of the campaign. Maximum 255 characters. The ID of the assistant to use for the campaign. Must be an outbound-capable assistant. Timezone identifier for the campaign (e.g., `America/New_York`, `Europe/London`). Defaults to your account timezone. Maximum number of simultaneous calls. Minimum: 1. Maximum depends on your plan's parallel calls limit (up to 10). Start of the allowed calling window in `H:i` format (e.g., `09:00`). End of the allowed calling window in `H:i` format (e.g., `17:00`). Array of weekday names when calls are allowed. Valid values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Maximum number of retry attempts for failed calls. Range: 1-5. Interval in minutes between retry attempts. Range: 10-4320 (up to 3 days). Whether to retry calls that reached voicemail. Whether to retry calls where the goal was not completed. Name of a boolean variable from your assistant's post-call schema to track goal completion. Maximum 255 characters. Whether to automatically mark the campaign as complete when there are no remaining leads to call. Array of phone number IDs to use for the campaign. Each ID must be a distinct integer. ### Response Success message confirming the campaign was created The created campaign data The ID of the created campaign The name of the campaign The status of the campaign (starts as `draft`) Maximum number of simultaneous calls Whether to mark the campaign as complete when there are no leads Start of the allowed calling window End of the allowed calling window Days of the week when calls are allowed Maximum number of retry attempts Interval in minutes between retries Timestamp when the campaign was created Timestamp when the campaign was last updated ### Error Responses Error message when the user has reached their plan's campaign limit Error message when the specified assistant is not found or is not an outbound assistant Error message indicating validation failure Detailed validation errors for each field ```json 201 Created theme={null} { "message": "Campaign created successfully", "data": { "id": 1, "name": "Product Demo Campaign", "status": "draft", "max_calls_in_parallel": 3, "mark_complete_when_no_leads": true, "allowed_hours_start_time": "09:00:00", "allowed_hours_end_time": "17:00:00", "allowed_days": [ "monday", "tuesday", "wednesday", "thursday", "friday" ], "max_retries": 3, "retry_interval": 60, "created_at": "2026-02-23T10:00:00.000000Z", "updated_at": "2026-02-23T10:00:00.000000Z" } } ``` ```json 403 Forbidden theme={null} { "message": "You have reached the maximum number of campaigns allowed by your plan." } ``` ```json 404 Not Found theme={null} { "message": "Assistant not found or not an outbound assistant." } ``` ```json 422 Validation Error theme={null} { "message": "The given data was invalid.", "errors": { "name": [ "The name field is required." ], "assistant_id": [ "The assistant id field is required." ] } } ``` # List campaigns Source: https://docs.repforce.ai/api-reference/campaigns/get-campaigns GET /user/campaigns List all campaigns This endpoint allows you to list all campaigns. ### Response fields The id of the campaign The name of the campaign The status of the campaign Maximum number of calls that can be made in parallel Whether to mark the campaign as complete when there are no leads The start time for allowed calling hours The end time for allowed calling hours The days of the week when calls are allowed Maximum number of retry attempts for failed calls Interval in seconds between retry attempts The timestamp when the campaign was created The timestamp when the campaign was last updated ```json 200 Response theme={null} [ { "id": 1, "name": "Test campaing", "status": "draft", "max_calls_in_parallel": 3, "mark_complete_when_no_leads": true, "allowed_hours_start_time": "00:00:00", "allowed_hours_end_time": "23:59:00", "allowed_days": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "max_retries": 3, "retry_interval": 60, "created_at": "2025-05-29T07:18:34.000000Z", "updated_at": "2025-05-29T07:18:34.000000Z" } ] ``` # Update campaign status Source: https://docs.repforce.ai/api-reference/campaigns/update-status POST /user/campaigns/update-status Start or stop a campaign in the RepForce.ai system This endpoint allows you to start or stop a campaign in the RepForce.ai system. ### Request body The ID of the campaign to update The action to perform on the campaign. Must be either "start" or "stop" ### Response The message of the response Whether the operation was successful The data of the response The ID of the updated campaign The new status of the campaign (e.g., "in-progress" for started campaigns, "stopped" for stopped campaigns) # Create Conversation Source: https://docs.repforce.ai/api-reference/conversations/create-conversation POST /conversations Create a new conversation session with an AI assistant This endpoint creates a new conversation session with an AI assistant. Use this to initiate a text-based chat session through your web widget or application. ### Request Body The UUID of the assistant to start the conversation with. Must be a valid assistant UUID that exists in the system. The type of conversation. Possible values: * `widget` - Web widget conversation (default, charged) * `test` - Test conversation (free, for development) Custom variables to pass to the assistant. These variables can be used in the assistant's system prompt and initial message using `{{variable_name}}` syntax. Common use cases: * Pre-filling customer information from forms * Passing context from your application * Customizing assistant behavior per session ### Response Fields Indicates whether the request was successful The unique UUID identifier for the created conversation. Use this ID for subsequent message requests. The initial conversation history. If the assistant has an initial message configured, it will be included here. The message role: `assistant` or `user` The message content ### Error Responses Will be `false` when an error occurs Error message describing what went wrong. Possible values: * `Assistant not found` - The provided assistant\_id does not exist * `Insufficient balance. Please top up your account.` - The assistant owner's account balance is too low ```bash cURL theme={null} curl -X POST "https://app.repforce.ai/api/conversations" \ -H "Content-Type: application/json" \ -d '{ "assistant_id": "550e8400-e29b-41d4-a716-446655440000", "type": "widget", "variables": { "customer_name": "John Smith", "company": "Acme Corp", "source": "pricing_page" } }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://app.repforce.ai/api/conversations', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ assistant_id: '550e8400-e29b-41d4-a716-446655440000', type: 'widget', variables: { customer_name: 'John Smith', company: 'Acme Corp', source: 'pricing_page' } }) }); const data = await response.json(); console.log(data.conversation_id); ``` ```python Python theme={null} import requests response = requests.post( 'https://app.repforce.ai/api/conversations', json={ 'assistant_id': '550e8400-e29b-41d4-a716-446655440000', 'type': 'widget', 'variables': { 'customer_name': 'John Smith', 'company': 'Acme Corp', 'source': 'pricing_page' } } ) data = response.json() print(data['conversation_id']) ``` ```json 200 Success theme={null} { "status": true, "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "history": [ { "role": "assistant", "content": "Hello John Smith! Welcome to Acme Corp support. How can I help you today?" } ] } ``` ```json 200 Success (No initial message) theme={null} { "status": true, "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "history": [] } ``` ```json 404 Assistant Not Found theme={null} { "status": false, "error": "Assistant not found" } ``` ```json 400 Insufficient Balance theme={null} { "status": false, "error": "Insufficient balance. Please top up your account." } ``` ## Pricing * **Widget conversations**: \$0.01 per user message * **Test conversations**: Free (for development and testing) ## Next Steps After creating a conversation, use the [Send Message](/api-reference/conversations/send-message) endpoint to exchange messages with the assistant. # Get Conversation Source: https://docs.repforce.ai/api-reference/conversations/get-conversation GET /conversations/{uuid} Retrieve the message history of a conversation This endpoint retrieves the complete message history of an existing conversation. Use this to display previous messages when resuming a conversation or to review conversation content. ### Path Parameters The unique UUID identifier of the conversation to retrieve ### Response Fields Indicates whether the request was successful Array of messages in the conversation, ordered chronologically (oldest first). The message role: `assistant` or `user` The message content Optional. Array of function calls made by the assistant during this message (e.g., calendar bookings, API calls). ### Error Responses Will be `false` when an error occurs Error message. Possible values: * `Conversation not found` - The provided UUID does not match any conversation ```bash cURL theme={null} curl -X GET "https://app.repforce.ai/api/conversations/7c9e6679-7425-40de-944b-e07fc1f90ae7" ``` ```javascript JavaScript theme={null} const conversationId = '7c9e6679-7425-40de-944b-e07fc1f90ae7'; const response = await fetch( `https://app.repforce.ai/api/conversations/${conversationId}` ); const data = await response.json(); console.log(data.history); ``` ```python Python theme={null} import requests conversation_id = '7c9e6679-7425-40de-944b-e07fc1f90ae7' response = requests.get( f'https://app.repforce.ai/api/conversations/{conversation_id}' ) data = response.json() print(data['history']) ``` ```json 200 Success theme={null} { "status": true, "history": [ { "role": "assistant", "content": "Hello! Welcome to our support. How can I help you today?" }, { "role": "user", "content": "I'd like to schedule a demo" }, { "role": "assistant", "content": "I'd be happy to help you schedule a demo! I have availability tomorrow at 2 PM or Thursday at 10 AM. Which works better for you?", "function_calls": [ { "name": "check_calendar_availability", "arguments": { "date_range": "next_7_days" }, "result": { "available_slots": ["2025-01-10 14:00", "2025-01-12 10:00"] } } ] }, { "role": "user", "content": "Thursday at 10 AM works for me" }, { "role": "assistant", "content": "I've scheduled your demo for Thursday, January 12th at 10 AM. You'll receive a calendar invitation shortly. Is there anything specific you'd like us to cover during the demo?", "function_calls": [ { "name": "book_appointment", "arguments": { "datetime": "2025-01-12T10:00:00", "title": "Product Demo" }, "result": { "success": true, "booking_id": "abc123" } } ] } ] } ``` ```json 404 Not Found theme={null} { "status": false, "error": "Conversation not found" } ``` ## Use Cases * **Resume conversations**: Retrieve history when a user returns to continue a conversation * **Analytics**: Review conversation content for quality assurance * **Integration**: Sync conversation data with your CRM or support system # List Conversations Source: https://docs.repforce.ai/api-reference/conversations/list-conversations GET /user/conversations List all conversations for the authenticated user with filtering and pagination This endpoint returns a paginated list of conversations belonging to the authenticated user's assistants. Use this to display conversation history, filter by type, or integrate with your CRM. This endpoint requires authentication. Pass your API key in the `Authorization` header as a Bearer token. ### Query Parameters Filter conversations by type. Possible values: `test`, `widget`, `whatsapp`, `api` Filter conversations by assistant ID (must belong to the authenticated user) Filter conversations from this date (YYYY-MM-DD format) Filter conversations until this date (YYYY-MM-DD format) Number of conversations per page (1-100, default: 15) Page number (default: 1) ### Response Fields The unique UUID identifier of the conversation The UUID of the assistant handling this conversation The name of the assistant handling this conversation The conversation type: `test`, `widget`, `whatsapp`, or `api` Total number of messages in the conversation The total cost of the conversation in USD Whether AI responses are enabled for this conversation The date and time when the conversation was created The date and time when the conversation was last updated The current page number Number of items per page Total number of conversations matching the criteria The last page number ```bash cURL theme={null} curl -X GET "https://app.repforce.ai/api/user/conversations?type=widget&per_page=10" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://app.repforce.ai/api/user/conversations?type=widget&per_page=10', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const data = await response.json(); console.log(data.data); // Array of conversations ``` ```python Python theme={null} import requests response = requests.get( 'https://app.repforce.ai/api/user/conversations', headers={'Authorization': 'Bearer YOUR_API_KEY'}, params={ 'type': 'widget', 'per_page': 10 } ) data = response.json() print(data['data']) ``` ```json 200 Response theme={null} { "current_page": 1, "data": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "assistant_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "assistant_name": "Support Assistant", "type": "widget", "message_count": 12, "total_cost": 0.0045, "ai_enabled": true, "created_at": "2025-01-25 14:30:00", "updated_at": "2025-01-25 14:45:22" }, { "id": "8d0f7780-8536-51ef-055c-f18fd2g01bf8", "assistant_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "assistant_name": "Support Assistant", "type": "whatsapp", "message_count": 8, "total_cost": 0.0032, "ai_enabled": true, "created_at": "2025-01-25 10:15:00", "updated_at": "2025-01-25 10:28:45" } ], "first_page_url": "https://app.repforce.ai/api/user/conversations?page=1", "from": 1, "last_page": 5, "last_page_url": "https://app.repforce.ai/api/user/conversations?page=5", "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://app.repforce.ai/api/user/conversations?page=1", "label": "1", "active": true }, { "url": "https://app.repforce.ai/api/user/conversations?page=2", "label": "2", "active": false } ], "next_page_url": "https://app.repforce.ai/api/user/conversations?page=2", "path": "https://app.repforce.ai/api/user/conversations", "per_page": 15, "prev_page_url": null, "to": 15, "total": 68 } ``` ## Conversation Types | Type | Description | | ---------- | ---------------------------------------------------------------- | | `test` | Internal test conversations from the assistant testing interface | | `widget` | Conversations from the web chat widget | | `whatsapp` | WhatsApp Business conversations | | `api` | Conversations created via the API | ## Use Cases * **Analytics Dashboard**: Display conversation metrics and trends * **CRM Integration**: Sync conversation data with your customer database * **Quality Monitoring**: Review conversation volumes by type and assistant * **Billing Review**: Track conversation costs across your organization # Send Message Source: https://docs.repforce.ai/api-reference/conversations/send-message POST /conversations/{uuid}/messages Send a message in an existing conversation and receive the assistant's response This endpoint sends a user message to an existing conversation and returns the assistant's response. The assistant processes the message using the configured AI model and any available tools. ### Path Parameters The unique UUID identifier of the conversation ### Request Body The user's message to send to the assistant. Maximum length: 2000 characters. ### Response Fields Indicates whether the request was successful The assistant's response to the user's message Array of function calls made by the assistant while processing the message. Empty array if no functions were called. The name of the function that was called The arguments passed to the function The result returned by the function ### Error Responses Will be `false` when an error occurs Error message. Possible values: * `Conversation not found` - The provided UUID does not match any conversation * `Insufficient balance. Please top up your account.` - The assistant owner's account balance is too low * `Failed to process message: [details]` - An error occurred while processing the message ```bash cURL theme={null} curl -X POST "https://app.repforce.ai/api/conversations/7c9e6679-7425-40de-944b-e07fc1f90ae7/messages" \ -H "Content-Type: application/json" \ -d '{ "message": "I would like to schedule a demo for next week" }' ``` ```javascript JavaScript theme={null} const conversationId = '7c9e6679-7425-40de-944b-e07fc1f90ae7'; const response = await fetch( `https://app.repforce.ai/api/conversations/${conversationId}/messages`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ message: 'I would like to schedule a demo for next week' }) } ); const data = await response.json(); console.log(data.message); ``` ```python Python theme={null} import requests conversation_id = '7c9e6679-7425-40de-944b-e07fc1f90ae7' response = requests.post( f'https://app.repforce.ai/api/conversations/{conversation_id}/messages', json={ 'message': 'I would like to schedule a demo for next week' } ) data = response.json() print(data['message']) ``` ```json 200 Success theme={null} { "status": true, "message": "I'd be happy to help you schedule a demo! I have availability on Monday at 2 PM, Wednesday at 10 AM, or Friday at 3 PM. Which time works best for you?", "function_calls": [] } ``` ```json 200 Success (With Function Calls) theme={null} { "status": true, "message": "I've checked our calendar and found several available slots for next week. I can offer you Monday at 2 PM, Wednesday at 10 AM, or Friday at 3 PM. Which would you prefer?", "function_calls": [ { "name": "check_calendar_availability", "arguments": { "start_date": "2025-01-13", "end_date": "2025-01-17" }, "result": { "available_slots": [ "2025-01-13 14:00", "2025-01-15 10:00", "2025-01-17 15:00" ] } } ] } ``` ```json 404 Not Found theme={null} { "status": false, "error": "Conversation not found" } ``` ```json 400 Insufficient Balance theme={null} { "status": false, "error": "Insufficient balance. Please top up your account." } ``` ```json 400 Processing Error theme={null} { "status": false, "error": "Failed to process message: Connection timeout" } ``` ```json 422 Validation Error theme={null} { "message": "The message field is required.", "errors": { "message": ["The message field is required."] } } ``` ## Pricing Each user message in a **widget** conversation costs **\$0.01**. Test conversations are free. ## Function Calls The assistant may execute functions during message processing, such as: * **Calendar operations**: Checking availability, booking appointments * **Knowledge base queries**: Searching documentation or FAQs * **Custom integrations**: Calling your configured webhook endpoints Function call results are included in the response so you can display relevant information to the user or track actions taken. ## Best Practices 1. **Handle errors gracefully**: Display user-friendly messages when errors occur 2. **Show loading states**: The assistant may take a few seconds to respond, especially when executing functions 3. **Preserve conversation ID**: Store the conversation UUID to allow users to resume conversations 4. **Respect rate limits**: Implement appropriate delays between messages if needed # Introduction Source: https://docs.repforce.ai/api-reference/introduction Welcome to the RepForce.ai API Welcome to the RepForce.ai API documentation. Our API allows you to programmatically interact with the RepForce.ai platform, enabling you to create and manage leads, schedule calls, and more. ## Base URL All API requests should be made to the following base URL: ``` https://app.repforce.ai/api ``` # Create document Source: https://docs.repforce.ai/api-reference/knowledgebases/create-document POST /user/knowledgebases/{knowledgebaseId}/documents Add a new document to a knowledgebase This endpoint creates a new document in a knowledgebase. Documents are processed asynchronously - the endpoint returns immediately while processing continues in the background. ### Path Parameters The unique identifier of the knowledgebase ### Request Body The name of the document (max 255 characters) Optional description of the document (max 255 characters) Document type: `website`, `pdf`, `txt`, or `docx` #### Website Documents The main URL to scrape. Required if `links` is not provided. Array of specific URLs to scrape. Required if `url` is not provided. A valid URL to include in the document Maximum number of relative links to follow when scraping (1-50) #### File Documents (PDF, TXT, DOCX) The file to upload (max 20MB). Use `multipart/form-data` encoding. ### Response Success message The created document object The unique identifier of the document The name of the document Description of the document Document type Human-readable type label Processing status (will be `processing` initially) Human-readable status label ISO 8601 timestamp of creation ```json 201 Website Document Created theme={null} { "message": "Document created successfully. Processing will begin shortly.", "data": { "id": 1, "name": "Company Website", "description": "Main website content", "type": "website", "type_label": "Website", "status": "processing", "status_label": "Processing", "created_at": "2025-01-08T10:30:00.000000Z" } } ``` ```json 201 PDF Document Created theme={null} { "message": "Document created successfully. Processing will begin shortly.", "data": { "id": 2, "name": "Product Manual", "description": "User guide for our product", "type": "pdf", "type_label": "PDF", "status": "processing", "status_label": "Processing", "created_at": "2025-01-08T10:35:00.000000Z" } } ``` ```json 404 Knowledgebase Not Found theme={null} { "error": "Knowledgebase not found." } ``` ```json 422 Validation Error theme={null} { "message": "A file is required for this document type.", "errors": { "file": [ "A file is required for this document type." ] } } ``` ```json 500 Processing Error theme={null} { "error": "Failed to create document. Please try again." } ``` ### Document Types | Type | Description | Input | | --------- | ------------------------------------------- | ------------------- | | `website` | Scrapes web pages and extracts text content | URL or list of URLs | | `pdf` | Extracts text from PDF files | PDF file upload | | `txt` | Plain text content | TXT file upload | | `docx` | Extracts text from Word documents | DOCX file upload | ### Example: Creating a Website Document ```bash theme={null} curl -X POST https://app.repforce.ai/api/user/knowledgebases/1/documents \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Company Website", "description": "Main website content", "type": "website", "url": "https://example.com", "relative_links_limit": 20 }' ``` ### Example: Uploading a PDF Document ```bash theme={null} curl -X POST https://app.repforce.ai/api/user/knowledgebases/1/documents \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "name=Product Manual" \ -F "description=User guide for our product" \ -F "type=pdf" \ -F "file=@/path/to/document.pdf" ``` Document processing is asynchronous. Poll the [get document](/api-reference/knowledgebases/get-document) endpoint to check when processing is complete. # Create knowledgebase Source: https://docs.repforce.ai/api-reference/knowledgebases/create-knowledgebase POST /user/knowledgebases Create a new knowledgebase This endpoint creates a new knowledgebase. After creation, you can add documents to it using the [create document](/api-reference/knowledgebases/create-document) endpoint. ### Request Body The name of the knowledgebase (max 255 characters) Optional description of the knowledgebase (max 255 characters) ### Response Success message The created knowledgebase object The unique identifier of the knowledgebase The name of the knowledgebase Description of the knowledgebase Current status (will be `empty` for new knowledgebases) Human-readable status label ISO 8601 timestamp of creation ISO 8601 timestamp of last update ```json 201 Created theme={null} { "message": "Knowledgebase created successfully.", "data": { "id": 1, "name": "Product Documentation", "description": "Technical documentation for our products", "status": "empty", "status_label": "Empty", "created_at": "2025-01-08T10:30:00.000000Z", "updated_at": "2025-01-08T10:30:00.000000Z" } } ``` ```json 422 Validation Error theme={null} { "message": "The name field is required.", "errors": { "name": [ "The name field is required." ] } } ``` ```json 500 Error theme={null} { "error": "Failed to create knowledgebase. Please try again." } ``` ### Next Steps After creating a knowledgebase, you'll want to: 1. **Add documents** - Use the [create document](/api-reference/knowledgebases/create-document) endpoint to add content 2. **Wait for processing** - Documents are processed asynchronously 3. **Attach to assistant** - Use the [update assistant](/api-reference/assistants/update-assistant) endpoint to attach the knowledgebase # Delete document Source: https://docs.repforce.ai/api-reference/knowledgebases/delete-document DELETE /user/knowledgebases/{knowledgebaseId}/documents/{documentId} Delete a document from a knowledgebase This endpoint permanently deletes a document from a knowledgebase. The document's vector embeddings are also removed from the vector database. ### Path Parameters The unique identifier of the knowledgebase The unique identifier of the document to delete ### Response Success message ```json 200 Response theme={null} { "message": "Document deleted successfully." } ``` ```json 404 Knowledgebase Not Found theme={null} { "error": "Knowledgebase not found." } ``` ```json 404 Document Not Found theme={null} { "error": "Document not found." } ``` ```json 500 Error theme={null} { "error": "Failed to delete document. Please try again." } ``` ### What Gets Deleted When you delete a document: * **Document record** is removed from the database * **Vector embeddings** are deleted from the vector database * **Processed content** is removed from external document stores * **Parent knowledgebase status** is updated automatically This action is irreversible. The document and all its processed content will be permanently deleted. If this was the last document in the knowledgebase, the knowledgebase status will change to `empty`. # Delete knowledgebase Source: https://docs.repforce.ai/api-reference/knowledgebases/delete-knowledgebase DELETE /user/knowledgebases/{id} Delete a knowledgebase and all its documents This endpoint permanently deletes a knowledgebase and all its associated documents. This action cannot be undone. ### Path Parameters The unique identifier of the knowledgebase to delete ### Response Success message ```json 200 Response theme={null} { "message": "Knowledgebase deleted successfully." } ``` ```json 404 Not Found theme={null} { "error": "Knowledgebase not found." } ``` ### What Gets Deleted When you delete a knowledgebase: * **All documents** in the knowledgebase are permanently deleted * **Vector embeddings** are removed from the vector database * **Document store data** is cleaned up from external services ### What Happens to Attached Assistants Any assistants that were using this knowledgebase will have their knowledgebase reference removed. They will continue to function but without the knowledgebase context. This action is irreversible. All documents and their processed content will be permanently deleted. Make sure you want to delete this knowledgebase before proceeding. # Get document Source: https://docs.repforce.ai/api-reference/knowledgebases/get-document GET /user/knowledgebases/{knowledgebaseId}/documents/{documentId} Get a single document by ID This endpoint returns the details of a specific document within a knowledgebase. ### Path Parameters The unique identifier of the knowledgebase The unique identifier of the document ### Response The document object The unique identifier of the document The name of the document Optional description of the document Document type: `website`, `pdf`, `txt`, or `docx` Human-readable type label Processing status: `processing`, `active`, or `failed` Human-readable status label ISO 8601 timestamp of creation ISO 8601 timestamp of last update ```json 200 Response theme={null} { "data": { "id": 1, "name": "Product Manual", "description": "Complete product user manual", "type": "pdf", "type_label": "PDF", "status": "active", "status_label": "Active", "created_at": "2025-01-05T10:30:00.000000Z", "updated_at": "2025-01-05T10:35:00.000000Z" } } ``` ```json 404 Knowledgebase Not Found theme={null} { "error": "Knowledgebase not found." } ``` ```json 404 Document Not Found theme={null} { "error": "Document not found." } ``` # Get documents Source: https://docs.repforce.ai/api-reference/knowledgebases/get-documents GET /user/knowledgebases/{knowledgebaseId}/documents Get all documents in a knowledgebase This endpoint returns a list of all documents in a specific knowledgebase. ### Path Parameters The unique identifier of the knowledgebase ### Response Array of document objects The unique identifier of the document The name of the document Optional description of the document Document type: `website`, `pdf`, `txt`, or `docx` Human-readable type label Processing status: `processing`, `active`, or `failed` Human-readable status label ISO 8601 timestamp of creation ISO 8601 timestamp of last update ```json 200 Response theme={null} { "data": [ { "id": 1, "name": "Product Manual", "description": "Complete product user manual", "type": "pdf", "type_label": "PDF", "status": "active", "status_label": "Active", "created_at": "2025-01-05T10:30:00.000000Z", "updated_at": "2025-01-05T10:35:00.000000Z" }, { "id": 2, "name": "Company Website", "description": "Main website content", "type": "website", "type_label": "Website", "status": "processing", "status_label": "Processing", "created_at": "2025-01-08T09:00:00.000000Z", "updated_at": "2025-01-08T09:00:00.000000Z" } ] } ``` ```json 404 Knowledgebase Not Found theme={null} { "error": "Knowledgebase not found." } ``` ### Document Statuses | Status | Description | | ------------ | -------------------------------------------------------------- | | `processing` | Document is being parsed and embedded into the vector database | | `active` | Document has been processed and is ready for use | | `failed` | Document processing failed | # Get knowledgebase Source: https://docs.repforce.ai/api-reference/knowledgebases/get-knowledgebase GET /user/knowledgebases/{id} Get a single knowledgebase by ID This endpoint returns the details of a specific knowledgebase. ### Path Parameters The unique identifier of the knowledgebase ### Response The knowledgebase object The unique identifier of the knowledgebase The name of the knowledgebase Optional description of the knowledgebase Current status: `empty`, `processing`, `active`, or `failed` Human-readable status label Number of documents in this knowledgebase Number of assistants using this knowledgebase ISO 8601 timestamp of creation ISO 8601 timestamp of last update ```json 200 Response theme={null} { "data": { "id": 1, "name": "Product Documentation", "description": "Technical documentation for our products", "status": "active", "status_label": "Active", "documents_count": 5, "assistants_count": 2, "created_at": "2025-01-05T10:30:00.000000Z", "updated_at": "2025-01-08T14:20:00.000000Z" } } ``` ```json 404 Not Found theme={null} { "error": "Knowledgebase not found." } ``` # Get knowledgebases Source: https://docs.repforce.ai/api-reference/knowledgebases/get-knowledgebases GET /user/knowledgebases Get all knowledgebases for the authenticated user This endpoint returns a list of all knowledgebases associated with your account. Knowledgebases are used to store documents that provide context and information to your AI assistants. ### Response Array of knowledgebase objects The unique identifier of the knowledgebase The name of the knowledgebase Optional description of the knowledgebase Current status: `empty`, `processing`, `active`, or `failed` Human-readable status label Number of documents in this knowledgebase Number of assistants using this knowledgebase ISO 8601 timestamp of creation ISO 8601 timestamp of last update ```json 200 Response theme={null} { "data": [ { "id": 1, "name": "Product Documentation", "description": "Technical documentation for our products", "status": "active", "status_label": "Active", "documents_count": 5, "assistants_count": 2, "created_at": "2025-01-05T10:30:00.000000Z", "updated_at": "2025-01-08T14:20:00.000000Z" }, { "id": 2, "name": "FAQ Knowledge", "description": "Frequently asked questions and answers", "status": "processing", "status_label": "Processing", "documents_count": 1, "assistants_count": 0, "created_at": "2025-01-08T09:00:00.000000Z", "updated_at": "2025-01-08T09:05:00.000000Z" } ] } ``` ```json 200 Empty Response theme={null} { "data": [] } ``` ### Knowledgebase Statuses | Status | Description | | ------------ | ----------------------------------------- | | `empty` | Knowledgebase has no documents | | `processing` | One or more documents are being processed | | `active` | All documents are processed and ready | | `failed` | One or more documents failed to process | # Update document Source: https://docs.repforce.ai/api-reference/knowledgebases/update-document PUT /user/knowledgebases/{knowledgebaseId}/documents/{documentId} Update a document's name or description This endpoint updates the metadata of an existing document. You can only update the name and description - the document type and content cannot be changed. ### Path Parameters The unique identifier of the knowledgebase The unique identifier of the document to update ### Request Body The new name for the document (max 255 characters) The new description for the document (max 255 characters) ### Response Success message The updated document object The unique identifier of the document The name of the document Description of the document Document type Human-readable type label Processing status Human-readable status label ISO 8601 timestamp of last update ```json 200 Response theme={null} { "message": "Document updated successfully.", "data": { "id": 1, "name": "Updated Product Manual", "description": "Revised user guide with new features", "type": "pdf", "type_label": "PDF", "status": "active", "status_label": "Active", "updated_at": "2025-01-08T15:45:00.000000Z" } } ``` ```json 404 Knowledgebase Not Found theme={null} { "error": "Knowledgebase not found." } ``` ```json 404 Document Not Found theme={null} { "error": "Document not found." } ``` ```json 422 Validation Error theme={null} { "message": "The name may not be greater than 255 characters.", "errors": { "name": [ "The name may not be greater than 255 characters." ] } } ``` To update the content of a document, you need to delete the existing document and create a new one with the updated content. # Update knowledgebase Source: https://docs.repforce.ai/api-reference/knowledgebases/update-knowledgebase PUT /user/knowledgebases/{id} Update an existing knowledgebase This endpoint updates the name and/or description of an existing knowledgebase. ### Path Parameters The unique identifier of the knowledgebase to update ### Request Body The new name for the knowledgebase (max 255 characters) The new description for the knowledgebase (max 255 characters) ### Response Success message The updated knowledgebase object The unique identifier of the knowledgebase The name of the knowledgebase Description of the knowledgebase Current status Human-readable status label ISO 8601 timestamp of last update ```json 200 Response theme={null} { "message": "Knowledgebase updated successfully.", "data": { "id": 1, "name": "Updated Product Documentation", "description": "Updated description for our technical docs", "status": "active", "status_label": "Active", "updated_at": "2025-01-08T15:45:00.000000Z" } } ``` ```json 404 Not Found theme={null} { "error": "Knowledgebase not found." } ``` ```json 422 Validation Error theme={null} { "message": "The name may not be greater than 255 characters.", "errors": { "name": [ "The name may not be greater than 255 characters." ] } } ``` Updating a knowledgebase's name or description does not affect its documents or processing status. # Create lead Source: https://docs.repforce.ai/api-reference/leads/create POST /user/lead Create a new lead in the RepForce.ai system This endpoint allows you to create a new lead in the RepForce.ai system. ### Request body The phone number of the lead in E.164 format (e.g. +1234567890) The ID of the campaign to create the lead for Custom variables to pass to the lead. You can include **any variables that are defined on your assistant** (see [Call variables](/ai-assistants/settings/prompt-and-tools#call-variables)). The examples below are just for illustration — use your own variable names as configured in the assistant settings. e.g. the name of the customer e.g. the email of the customer Whether to allow duplicate leads in a campaign. Array of secondary contact leads to create along with the main lead The phone number of the secondary contact in E.164 format The variables to pass to the secondary contact The name of the secondary contact The email of the secondary contact ### Response The message of the response The lead data object The unique ID of the created lead The ID of the campaign this lead belongs to The phone number of the lead in E.164 format The variables associated with the lead The name of the customer The email of the customer The status of the lead The timestamp when the lead was created The timestamp when the lead was last updated The campaign information The id of the campaign The name of the campaign Array of secondary contact leads associated with this lead The id of the secondary contact lead The phone number of the secondary contact in E.164 format The variables associated with the secondary contact The status of the secondary contact The created at date of the secondary contact The updated at date of the secondary contact ```json 200 Response theme={null} { "message": "Lead created successfully", "data": { "id": 1, "campaign_id": 1, "phone_number": "+1234567890", "variables": { "customer_name": "John Doe", "email": "john.doe@example.com" }, "status": "created", "created_at": "2025-06-30 11:53:20", "updated_at": "2025-06-30 11:53:20", "campaign": { "id": 1, "name": "My new campaign" }, "secondary_contacts": [ { "id": 2, "phone_number": "+1234567891", "variables": { "customer_name": "Jane Doe Secondary", "email": "jane.doe.secondary@example.com" }, "status": "created", "created_at": "2025-06-30 11:53:20", "updated_at": "2025-06-30 11:53:20" }, { "id": 3, "phone_number": "+1234567892", "variables": { "customer_name": "Bob Doe Office", "email": "bob.doe.office@example.com" }, "status": "created", "created_at": "2025-06-30 11:53:20", "updated_at": "2025-06-30 11:53:20" } ] } } ``` # Delete lead Source: https://docs.repforce.ai/api-reference/leads/delete DELETE /user/leads/{id} Delete a lead from the RepForce.ai system This endpoint allows you to delete a lead from the RepForce.ai system. ### Path Parameters The ID of the lead to delete ### Response The message of the response # List leads Source: https://docs.repforce.ai/api-reference/leads/get-lead GET /user/leads List all leads for the authenticated user with filtering and pagination options This endpoint allows you to list all leads belonging to the authenticated user with various filtering and pagination options. ### Query Parameters Filter leads by status. Possible values: `created`, `scheduled`, `processing`, `completed`, `rescheduled`, `reached-max-retries`, `blacklisted` Filter leads by campaign ID Filter leads by phone number (partial match supported) Filter leads created from this date (YYYY-MM-DD format) Filter leads created until this date (YYYY-MM-DD format) Number of leads per page (1-100, default: 15) Page number (default: 1) ### Response fields The id of the lead The ID of the campaign this lead belongs to The phone number of the lead in E.164 format The variables associated with the lead The status of the lead The created at date of the lead The updated at date of the lead The campaign information The id of the campaign The name of the campaign Array of secondary contact leads associated with this lead The id of the secondary contact lead The phone number of the secondary contact in E.164 format The variables associated with the secondary contact The status of the secondary contact The created at date of the secondary contact The updated at date of the secondary contact The current page number Number of items per page Total number of leads matching the criteria The last page number ```json 200 Response theme={null} { "current_page": 1, "data": [ { "id": 1, "campaign_id": 1, "phone_number": "+1234567890", "variables": { "customer_name": "John Doe", "email": "john.doe@example.com" }, "status": "created", "created_at": "2025-06-30 11:18:04", "updated_at": "2025-06-30 11:18:04", "campaign": { "id": 1, "name": "My new campaign" }, "secondary_contacts": [ { "id": 2, "phone_number": "+1234567899", "variables": { "customer_name": "Jane Doe Secondary", "email": "jane.doe.secondary@example.com" }, "status": "created", "created_at": "2025-06-30 11:18:04", "updated_at": "2025-06-30 11:18:04" } ] } ], "first_page_url": "https://app.repforce.ai/api/user/leads?page=1", "from": 1, "last_page": 10, "last_page_url": "https://app.repforce.ai/api/user/leads?page=10", "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://app.repforce.ai/api/user/leads?page=1", "label": "1", "active": true }, { "url": "https://app.repforce.ai/api/user/leads?page=2", "label": "2", "active": false } ], "next_page_url": "https://app.repforce.ai/api/user/leads?page=2", "path": "https://app.repforce.ai/api/user/leads", "per_page": 15, "prev_page_url": null, "to": 15, "total": 150 } ``` # Update Lead Source: https://docs.repforce.ai/api-reference/leads/update-lead PUT /user/leads/{id} Update an existing lead in your campaigns Update a lead by providing the lead ID and the fields you want to modify. Only the fields provided in the request will be updated. ## Path Parameters The ID of the lead to update ## Body Parameters The ID of the campaign to assign the lead to The phone number of the lead (will be formatted to E164) The status of the lead. Must be one of: `created`, `completed`, `reached-max-retries` Custom variables to merge with existing lead variables ## Response Success message indicating the lead was updated ```bash cURL theme={null} curl -X PUT "https://app.repforce.ai/api/user/leads/123" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaign_id": 456, "phone_number": "+1234567890", "variables": { "name": "John Doe", "company": "Acme Corp" } }' ``` ```json Success Response theme={null} { "message": "Lead updated successfully" } ``` ```json Error Response - Lead Not Found theme={null} { "message": "Lead not found" } ``` ```json Error Response - Campaign Not Found theme={null} { "message": "Campaign not found" } ``` ```json Error Response - Invalid Phone Number theme={null} { "message": "Invalid phone number" } ``` ```json Error Response - Validation Failed theme={null} { "message": "Validation failed", "errors": { "campaign_id": ["The selected campaign does not exist"], "status": ["This status is assigned automatically and cannot be set manually"], "variables": ["Variables must be an array"] } } ``` ```json Error Response - Invalid Fields theme={null} { "message": "Invalid fields: invalid_field, another_invalid_field" } ``` ## Notes * The lead must belong to the authenticated user * If updating the campaign, the new campaign must also belong to the authenticated user * Phone numbers are automatically formatted and validated * Variables are merged with existing variables (not replaced) * Only allowed fields can be updated: `campaign_id`, `phone_number`, `status`, `variables` * The `status` field has restricted values for data integrity # Create mid call tool Source: https://docs.repforce.ai/api-reference/mid-call-tools/create-tool POST /user/tools Create a new mid call tool This endpoint allows you to create a new mid call tool that can be used by your AI assistants to interact with external APIs during calls. ### Body Parameters Tool name - must contain only lowercase letters and underscores, and start with a letter (e.g., `get_weather`, `book_appointment`) Detailed explanation of when and how the AI should use this tool (max 255 characters) Valid URL of the API endpoint to call HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` Request timeout in seconds (1-30, default: 10) HTTP headers to send with the request Header name Header value Parameters that the AI will extract from conversation and send to the endpoint Parameter name (2-32 chars, must start with letter, can contain letters and underscores) Parameter type: `string`, `number`, or `boolean` Description to help AI understand how to extract this parameter (3-255 chars) ### Response fields Success message The created tool object The unique identifier of the tool The name of the tool Tool description API endpoint URL HTTP method Request timeout in seconds HTTP headers Parameter schema ISO 8601 timestamp ISO 8601 timestamp ```json 201 Created theme={null} { "message": "Tool created successfully", "data": { "id": 1, "name": "check_order_status", "description": "Use this tool to check the status of a customer's order.", "endpoint": "https://api.yourstore.com/orders/status", "method": "GET", "timeout": 10, "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "Authorization", "value": "Bearer sk_..." } ], "schema": [ { "name": "order_id", "type": "string", "description": "The customer's order ID" }, { "name": "order_number", "type": "number", "description": "The numeric order number" }, { "name": "priority_order", "type": "boolean", "description": "Whether this is a priority order" } ], "created_at": "2025-10-10T12:00:00.000000Z", "updated_at": "2025-10-10T12:00:00.000000Z" } } ``` ```json 422 Validation Error theme={null} { "message": "The name field must contain only lowercase letters and underscores, and start with a letter.", "errors": { "name": [ "Tool name must contain only lowercase letters and underscores, and start with a letter." ] } } ``` ```json 422 Plan Limit Reached theme={null} { "message": "You have reached your plan limit of 5 mid call tools. Please upgrade your plan to create more tools." } ``` ### Attaching Tools to Assistants After creating a tool, you need to attach it to an assistant to use it during calls. Tools are managed through the Assistant API: * **[Create Assistant](/api-reference/assistants/create-assistant)** - Use the `tool_ids` parameter to attach tools when creating an assistant * **[Update Assistant](/api-reference/assistants/update-assistant)** - Use the `tool_ids` parameter to add, remove, or replace tools on an existing assistant # Delete mid call tool Source: https://docs.repforce.ai/api-reference/mid-call-tools/delete-tool DELETE /user/tools/{id} Delete a mid call tool This endpoint allows you to permanently delete a mid call tool. This will also remove the tool from all assistants it was assigned to. ### Headers Bearer token for authentication Must be `application/json` Must be `application/json` ### Path Parameters The unique identifier of the tool to delete ### Response fields Success message confirming deletion ```json 200 OK theme={null} { "message": "Tool deleted successfully" } ``` ```json 404 Not Found theme={null} { "message": "Tool not found" } ``` ### Note When a tool is deleted, it is automatically removed from all assistants. To manage tool assignments without deleting the tool, use: * **[Update Assistant](/api-reference/assistants/update-assistant)** - Use the `tool_ids` parameter to remove tools from specific assistants # Get mid call tool Source: https://docs.repforce.ai/api-reference/mid-call-tools/get-tool GET /user/tools/{id} Retrieve a specific mid call tool by ID This endpoint allows you to retrieve detailed information about a specific mid call tool. ### Headers Bearer token for authentication Must be `application/json` Must be `application/json` ### Path Parameters The unique identifier of the tool ### Response fields The unique identifier of the tool The name of the tool (lowercase with underscores) Detailed explanation of when and how the AI should use this tool The API endpoint URL that will be called HTTP method (GET, POST, PUT, PATCH, DELETE) Request timeout in seconds (1-30) HTTP headers to send with the request Header name Header value Parameters that the AI will extract and send to the endpoint Parameter name Parameter type (string, number, boolean) Description to help AI understand how to extract this parameter ISO 8601 timestamp when the tool was created ISO 8601 timestamp when the tool was last updated ```json 200 Response theme={null} { "id": 1, "name": "get_weather", "description": "Use this tool to get the current weather in a specific city. Call this when the customer asks about weather conditions.", "endpoint": "https://api.openweathermap.org/data/2.5/weather", "method": "GET", "timeout": 10, "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "Authorization", "value": "Bearer sk_..." } ], "schema": [ { "name": "city", "type": "string", "description": "The city name to get weather for" }, { "name": "temperature", "type": "number", "description": "Current temperature value" }, { "name": "is_raining", "type": "boolean", "description": "Whether it is currently raining" } ], "created_at": "2025-10-10T12:00:00.000000Z", "updated_at": "2025-10-10T12:00:00.000000Z" } ``` ```json 404 Not Found theme={null} { "message": "Tool not found" } ``` ### Assigning Tools to Assistants To use this tool with an assistant, see: * **[Create Assistant](/api-reference/assistants/create-assistant)** - Attach tools using the `tool_ids` parameter * **[Update Assistant](/api-reference/assistants/update-assistant)** - Manage tool assignments using the `tool_ids` parameter # List mid call tools Source: https://docs.repforce.ai/api-reference/mid-call-tools/get-tools GET /user/tools Retrieve all mid call tools This endpoint allows you to retrieve all mid call tools. Mid call tools enable your AI assistants to interact with external APIs during a call. ### Headers Bearer token for authentication Must be `application/json` Must be `application/json` ### Response fields Array of mid call tools The unique identifier of the tool The name of the tool (lowercase with underscores) Detailed explanation of when and how the AI should use this tool The API endpoint URL that will be called HTTP method (GET, POST, PUT, PATCH, DELETE) Request timeout in seconds (1-30) HTTP headers to send with the request Header name Header value Parameters that the AI will extract and send to the endpoint Parameter name Parameter type (string, number, boolean) Description to help AI understand how to extract this parameter ISO 8601 timestamp when the tool was created ISO 8601 timestamp when the tool was last updated ```json 200 Response theme={null} [ { "id": 1, "name": "get_weather", "description": "Use this tool to get the current weather in a specific city. Call this when the customer asks about weather conditions.", "endpoint": "https://api.openweathermap.org/data/2.5/weather", "method": "GET", "timeout": 10, "headers": [ { "name": "Content-Type", "value": "application/json" }, { "name": "Authorization", "value": "Bearer sk_..." } ], "schema": [ { "name": "city", "type": "string", "description": "The city name to get weather for" }, { "name": "temperature", "type": "number", "description": "Current temperature value" }, { "name": "is_raining", "type": "boolean", "description": "Whether it is currently raining" } ], "created_at": "2025-10-10T12:00:00.000000Z", "updated_at": "2025-10-10T12:00:00.000000Z" }, { "id": 2, "name": "send_notification", "description": "Use this tool to send a notification to the customer. Call this when customer requests updates.", "endpoint": "https://api.yourcompany.com/notifications/send", "method": "POST", "timeout": 15, "headers": [ { "name": "Content-Type", "value": "application/json" } ], "schema": [ { "name": "message", "type": "string", "description": "The notification message to send" }, { "name": "priority_level", "type": "number", "description": "Priority level from 1 to 5" }, { "name": "send_sms", "type": "boolean", "description": "Whether to also send SMS notification" } ], "created_at": "2025-10-09T14:30:00.000000Z", "updated_at": "2025-10-10T09:15:00.000000Z" } ] ``` ### Assigning Tools to Assistants To use these tools with assistants, see: * **[Create Assistant](/api-reference/assistants/create-assistant)** - Attach tools using the `tool_ids` parameter * **[Update Assistant](/api-reference/assistants/update-assistant)** - Manage tool assignments using the `tool_ids` parameter # Update mid call tool Source: https://docs.repforce.ai/api-reference/mid-call-tools/update-tool PUT /user/tools/{id} Update an existing mid call tool This endpoint allows you to update an existing mid call tool. All fields are optional - only provide the fields you want to update. ### Path Parameters The unique identifier of the tool to update ### Body Parameters Tool name - must contain only lowercase letters and underscores, and start with a letter Detailed explanation of when and how the AI should use this tool (max 255 characters) Valid URL of the API endpoint to call HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` Request timeout in seconds (1-30) HTTP headers to send with the request (replaces existing headers) Header name Header value Parameters schema (replaces existing schema) Parameter name (2-32 chars) Parameter type: `string`, `number`, or `boolean` Parameter description (3-255 chars) ### Response fields Success message The updated tool object with all current values ```json 200 OK theme={null} { "message": "Tool updated successfully", "data": { "id": 1, "name": "update_customer_info", "description": "Use this tool to update customer information in the system.", "endpoint": "https://api.yourcompany.com/customers/update", "method": "POST", "timeout": 15, "headers": [ { "name": "Content-Type", "value": "application/json" } ], "schema": [ { "name": "customer_name", "type": "string", "description": "Full name of the customer" }, { "name": "customer_age", "type": "number", "description": "Age of the customer" }, { "name": "newsletter_subscription", "type": "boolean", "description": "Whether customer wants to subscribe to newsletter" } ], "created_at": "2025-10-10T12:00:00.000000Z", "updated_at": "2025-10-10T14:30:00.000000Z" } } ``` ```json 404 Not Found theme={null} { "message": "Tool not found" } ``` ```json 422 Validation Error theme={null} { "message": "Validation failed", "errors": { "name": ["Tool name must contain only lowercase letters and underscores, and start with a letter."] } } ``` ### Managing Tool Assignments To attach or detach this tool from assistants, use the Assistant API: * **[Create Assistant](/api-reference/assistants/create-assistant)** - Use the `tool_ids` parameter to attach tools when creating an assistant * **[Update Assistant](/api-reference/assistants/update-assistant)** - Use the `tool_ids` parameter to manage which tools are assigned to an assistant # Get all phone numbers Source: https://docs.repforce.ai/api-reference/phone-numbers/get-phone-numbers GET /user/phone-numbers/all Get all phone numbers owned by the authenticated user This endpoint returns a list of all phone numbers associated with your account, including their subscription status and capabilities. ### Response Array of phone number objects The unique identifier of the phone number The phone number in E.164 format (e.g., +14155551234) The ISO 3166-1 alpha-2 country code (e.g., US, GB, AU) The type of phone number: `normal`, `sip`, or `caller_id` Human-readable label for the phone number type Whether the phone number can send and receive SMS The region where the phone number is provisioned Whether the phone number has an active subscription ISO 8601 timestamp of when the phone number was purchased ```json 200 Response theme={null} { "data": [ { "id": 1, "phone_number": "+14155551234", "country_code": "US", "type": "normal", "type_label": "Dedicated Number", "sms_capable": true, "region": "us1", "has_active_subscription": true, "created_at": "2025-01-08T10:30:00.000000Z" }, { "id": 2, "phone_number": "+442071234567", "country_code": "GB", "type": "normal", "type_label": "Dedicated Number", "sms_capable": false, "region": "us1", "has_active_subscription": true, "created_at": "2025-01-05T14:20:00.000000Z" } ] } ``` There is also a legacy endpoint `GET /user/phone-numbers` that returns only SMS-capable phone numbers with active subscriptions. Use this `/all` endpoint if you need all phone numbers regardless of SMS capability or subscription status. # Purchase phone number Source: https://docs.repforce.ai/api-reference/phone-numbers/purchase-phone-number POST /user/phone-numbers/purchase Purchase a dedicated phone number This endpoint allows you to purchase a phone number that was found using the [search endpoint](/api-reference/phone-numbers/search-phone-numbers). The platform automatically handles pricing, billing, and provisioning. You must have a valid payment method on file before purchasing a phone number. The purchase creates a monthly subscription that will auto-renew. ### Request Body The phone number to purchase in E.164 format (e.g., +14155551234). Must be a number returned from the search endpoint. ### Response Success message The purchased phone number details The unique identifier of the phone number The phone number in E.164 format The ISO country code The phone number type (always `normal` for purchased numbers) Whether the number supports SMS ```json 201 Created theme={null} { "message": "Phone number purchased successfully.", "data": { "id": 123, "phone_number": "+14155551234", "country_code": "US", "type": "normal", "sms_capable": true } } ``` ```json 400 Already In Use theme={null} { "error": "This phone number is already in use." } ``` ```json 400 Not Available theme={null} { "error": "This phone number is not available for purchase. Please search for available numbers first." } ``` ```json 402 No Payment Method theme={null} { "error": "No payment method found. Please add a payment method to your account." } ``` ```json 402 Payment Failed theme={null} { "error": "Payment failed. Please update your payment method." } ``` ```json 422 Invalid Format theme={null} { "error": "Unable to parse phone number. Please provide a valid E.164 format number." } ``` ```json 500 Provider Error theme={null} { "error": "Failed to purchase phone number from provider. Please contact support." } ``` ### How It Works 1. **Search** - First use the [search endpoint](/api-reference/phone-numbers/search-phone-numbers) to find available numbers 2. **Purchase** - Submit the phone number you want to this endpoint 3. **Automatic Processing** - The platform: * Validates the number is still available * Determines the correct pricing based on country * Creates a monthly subscription on your payment method * Provisions the number with our telephony provider * Creates the phone number record in your account Phone number purchases are non-refundable. The subscription will continue until you [release the number](/api-reference/phone-numbers/release-phone-number). # Release phone number Source: https://docs.repforce.ai/api-reference/phone-numbers/release-phone-number DELETE /user/phone-numbers/{id} Release a phone number and cancel its subscription This endpoint releases a phone number from your account. For dedicated numbers with subscriptions, this cancels the subscription and the number will be released at the end of the current billing period. ### Path Parameters The unique identifier of the phone number to release ### Response Success message indicating the release status ```json 200 Subscription Cancelled theme={null} { "message": "Phone number released successfully. It will be removed at the end of the billing period." } ``` ```json 200 Immediately Deleted theme={null} { "message": "Phone number deleted successfully." } ``` ```json 400 Already Scheduled theme={null} { "error": "Phone number is already scheduled for release." } ``` ```json 404 Not Found theme={null} { "error": "Phone number not found." } ``` ```json 500 Error theme={null} { "error": "Failed to release phone number. Please try again or contact support." } ``` ### Release Behavior The release behavior depends on the phone number type: | Type | Behavior | | ---------------------- | ------------------------------------------------------------------------------------------------------- | | **Dedicated (normal)** | Subscription is cancelled. Number remains active until the end of the billing period, then is released. | | **SIP** | Immediately deleted from your account. | | **Caller ID** | Immediately deleted from your account and removed from the telephony provider. | Once a phone number is released, you may not be able to get the same number back. Make sure to update any assistants or campaigns using this number before releasing it. ### What Happens to Attached Resources When you release a phone number: * Any **inbound assistants** attached to this number will have their phone number unassigned * Any **campaigns** using this number will have it removed from their phone number rotation * **Call history** is preserved and remains accessible # Search available phone numbers Source: https://docs.repforce.ai/api-reference/phone-numbers/search-phone-numbers GET /user/phone-numbers/search Search for available phone numbers that can be purchased This endpoint allows you to search for available phone numbers from our provider. Use the results to find a number you want to purchase. ### Query Parameters The ISO 3166-1 alpha-2 country code to search in (e.g., US, GB, AU, CA) Filter phone numbers that contain specific digits (numeric characters only, max 10 digits) ### Response Array of available phone numbers The phone number in E.164 format The phone number formatted for display The ISO country code Monthly rental price in USD The Stripe price ID for billing Address requirements for this number: `none`, `local`, `foreign`, or `inventory` Whether the number supports SMS ```json 200 Response theme={null} { "data": [ { "phone_number": "+14155551234", "phone_number_formatted": "+1 415-555-1234", "country_code": "US", "price": 3.99, "stripe_price_id": "price_1PkA4dBXoZOzqQuAsvGvVJTZ", "address_requirements": "none", "sms_capable": true }, { "phone_number": "+14155555678", "phone_number_formatted": "+1 415-555-5678", "country_code": "US", "price": 3.99, "stripe_price_id": "price_1PkA4dBXoZOzqQuAsvGvVJTZ", "address_requirements": "none", "sms_capable": false } ] } ``` ```json 200 Empty Response theme={null} { "data": [] } ``` ### Supported Countries | Country | Code | | -------------- | ---- | | United States | US | | Canada | CA | | United Kingdom | GB | | Australia | AU | | Israel | IL | | Poland | PL | | Finland | FI | | Netherlands | NL | | Denmark | DK | | Italy | IT | # Send SMS Source: https://docs.repforce.ai/api-reference/sms/send-sms POST /user/sms Send an SMS message using your phone number This endpoint allows you to send SMS messages using your purchased phone numbers. The SMS will be sent via Twilio and costs will be automatically deducted from your account balance. ### Request Body The ID of your phone number to send the SMS from (must be SMS-capable) The recipient's phone number in international format (e.g., "+1234567890") The SMS message content (max 300 characters) ### Response Success message confirming SMS was sent The unique identifier of the SMS record The ID of the phone number used to send the SMS The recipient's phone number in E.164 format The SMS message content The ID of the user who sent the SMS Number of SMS segments (for billing purposes) Cost per SMS segment Total cost of the SMS (segment\_price \* segments) The current status of the SMS Twilio SMS SID for tracking The date and time when the SMS was created The date and time when the SMS was last updated ### Error Responses Error message describing the issue (invalid phone number, insufficient balance, etc.) Error message indicating SMS sending failure Detailed error information ```json 201 Success Response theme={null} { "message": "SMS sent successfully", "data": { "id": 456, "phone_number_id": 78, "to": "+1234567890", "body": "Hello! This is a test message from Your Company. How can we help you today?", "user_id": 1, "segments": 1, "segment_price": 0.0075, "total_cost": 0.0075, "status": "sent", "sms_sid": "SM1234567890abcdef1234567890abcdef", "created_at": "2025-08-04 15:30:00", "updated_at": "2025-08-04 15:30:02" } } ``` ```json 400 Bad Request theme={null} { "message": "From number not found" } ``` ```json 400 Bad Request theme={null} { "message": "Invalid to phone number" } ``` ```json 400 Bad Request theme={null} { "message": "Insufficient balance" } ``` ```json 400 Bad Request theme={null} { "message": "From number is not SMS capable" } ``` ```json 500 Internal Server Error theme={null} { "message": "Failed to send SMS", "error": "Twilio API error details" } ``` ### Notes * The sender phone number must belong to the authenticated user * The sender phone number must be SMS-capable * The phone number subscription must be active (not expired) * Sufficient account balance is required to cover SMS costs * Phone numbers are automatically formatted to E.164 format * SMS costs vary by destination country and are charged per segment * Long messages may be split into multiple segments, increasing the cost * The recipient phone number must be valid according to international standards # Get current user Source: https://docs.repforce.ai/api-reference/user/me GET /user/me Get the authenticated user's profile information This endpoint returns the profile information for the currently authenticated user, including their account balance. ### Response The user's full name The user's email address The user's current account balance in USD ```json 200 Response theme={null} { "name": "John Doe", "email": "john.doe@example.com", "total_balance": 125.50 } ``` ### Use Cases This endpoint is useful for: * **Verifying authentication** - Confirm the API key is valid and belongs to the expected user * **Checking account balance** - Monitor available credits before making API calls * **Displaying user info** - Show the current user in your application's UI # Conversation Ended Webhook Source: https://docs.repforce.ai/api-reference/webhooks/conversation-ended-webhook Webhook sent after a chat conversation ends containing transcript, extracted variables, and customer data The Conversation Ended Webhook is automatically sent to your specified webhook URL after a chat conversation (WhatsApp or Web Widget) ends. This webhook contains the full transcript, extracted variables, customer information, and sender details. ## Webhook Configuration To enable conversation ended webhooks: 1. Use the [Enable Conversation Ended Webhook](/api-reference/assistants/enable-conversation-ended-webhook) API endpoint 2. Provide your webhook URL where notifications will be sent 3. Optionally configure post-call variables on your assistant to extract structured data from conversations ## Request Format The webhook is sent as a POST request to your configured URL with the following JSON payload: ### Payload Structure Unique identifier (UUID) of the conversation Unique identifier (UUID) of the assistant that handled the conversation The type of conversation. Possible values: `widget`, `whatsapp` Total number of messages exchanged in the conversation Status of the conversation. Value: `ended` Variables extracted by AI based on your assistant's post-call schema configuration Whether the conversation objective was achieved Conversation summary Any custom variables you defined in the assistant configuration Variables that were passed to the assistant at the start of the conversation (e.g., from pre-chat form fields or automation flows) Array of message objects representing the full conversation The sender role: `assistant` or `user` The message content Human-readable formatted transcript with `AI:` and `Customer:` prefixes Customer phone number (available for WhatsApp conversations, `null` for widget conversations) Customer name if provided (e.g., from pre-chat form), or `null` WhatsApp sender information (only present for WhatsApp conversations, `null` for widget) The WhatsApp sender phone number The WhatsApp sender display name ISO 8601 timestamp when the conversation started (in the user's configured timezone) ISO 8601 timestamp when the conversation ended (in the user's configured timezone) ```json Conversation Ended Webhook Payload theme={null} { "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210", "type": "widget", "message_count": 8, "status": "ended", "extracted_variables": { "status": true, "summary": "Customer asked about pricing plans and was interested in the Pro plan" }, "input_variables": { "name": "John Doe", "email": "john@example.com" }, "transcript": [ { "role": "assistant", "content": "Hi! How can I help you today?" }, { "role": "user", "content": "I have a question about your service." }, { "role": "assistant", "content": "Of course! I'd be happy to help. What would you like to know?" }, { "role": "user", "content": "What are your pricing plans?" } ], "formatted_transcript": "AI: Hi! How can I help you today?\nCustomer: I have a question about your service.\nAI: Of course! I'd be happy to help. What would you like to know?\nCustomer: What are your pricing plans?", "customer_phone": null, "customer_name": "John Doe", "sender": null, "created_at": "2026-02-23T09:30:00+01:00", "ended_at": "2026-02-23T10:00:00+01:00" } ``` ```json WhatsApp Conversation Ended Webhook theme={null} { "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210", "type": "whatsapp", "message_count": 12, "status": "ended", "extracted_variables": { "status": true, "summary": "Customer scheduled an appointment for next week" }, "input_variables": {}, "transcript": [ { "role": "user", "content": "Hello, I'd like to book an appointment" }, { "role": "assistant", "content": "Hi! I'd be happy to help you book an appointment. What date works best for you?" } ], "formatted_transcript": "Customer: Hello, I'd like to book an appointment\nAI: Hi! I'd be happy to help you book an appointment. What date works best for you?", "customer_phone": "+1234567890", "customer_name": null, "sender": { "phone_number": "+19876543210", "display_name": "My Business" }, "created_at": "2026-02-23T14:00:00+01:00", "ended_at": "2026-02-23T14:25:00+01:00" } ``` ## Retry Behavior If your webhook endpoint returns a non-2xx status code or the request fails, the system will retry: | Attempt | Delay | | --------- | ----------- | | 1st retry | 30 seconds | | 2nd retry | 60 seconds | | 3rd retry | 120 seconds | After 3 failed attempts, the webhook delivery is marked as failed and no further retries are attempted. ## Important Notes * The `conversation_id` and `assistant_id` are UUIDs, not integer IDs * The `sender` field is only populated for WhatsApp conversations — it will be `null` for web widget conversations * The `customer_phone` is only available for WhatsApp conversations * The `customer_name` comes from pre-chat form data or conversation context * Timestamps use the user's configured timezone (ISO 8601 format) * The `extracted_variables` are populated from your assistant's post-call schema evaluation * The `input_variables` contain data from pre-chat forms (web widget) or automation flows # Post-Call Webhook Source: https://docs.repforce.ai/api-reference/webhooks/post-call-webhook Webhook sent after a call is completed containing extracted variables and call data The Post-Call Webhook is automatically sent to your specified webhook URL after each call is completed. This webhook contains call details, extracted variables, transcript, and optionally the recording URL. ## Webhook Configuration To enable post-call webhooks: 1. Configure your assistant's webhook URL in the [assistant settings](/ai-assistants/settings/post-call-actions#webhook-configuration) 2. Enable "Post call webhook" in the [assistant configuration](/ai-assistants/settings/post-call-actions#webhook-configuration) 3. Define post-call variables that the AI should extract ## Request Format The webhook is sent as a POST request to your configured URL with the following JSON payload: ### Payload Structure Unique identifier of the call Phone number of the customer in E.164 format (e.g., "+1234567890") or null if not available Phone number used by the assistant in E.164 format or null if not available Duration of the call in seconds Final status of the call (e.g., "completed", "busy", "failed") Variables extracted by AI based on your post-call schema configuration Whether the call objective was achieved Call summary in a few words Any custom variables you defined in the assistant configuration Variables that were passed to the assistant before the call started Full transcript of the conversation URL to download the call recording (only included if "Include recording in webhook" is enabled in [assistant settings](/ai-assistants/settings/post-call-actions#webhook-configuration)) ISO 8601 timestamp when the call was initiated ISO 8601 timestamp when the call was completed (uses updated\_at from the call record) Lead information (only included for campaign calls) Unique identifier of the lead Lead's phone number Variables associated with the lead Current status of the lead The number of call attempts made to this lead When the lead was created When the lead was last updated Campaign information (if available) Campaign ID Campaign name Campaign status Campaign allowed start time Campaign allowed end time Campaign allowed days Maximum concurrent calls for campaign Maximum retry attempts for leads Retry interval in minutes When the campaign was created When the campaign was last updated List of transfer calls made during this call (only included if the call has transfers) Unique identifier of the transfer call Final status of the transfer call (e.g., "completed", "busy", "failed") Phone number the call was transferred to in E.164 format Duration of the transfer call in seconds Carrier cost of the transfer call in USD Raw transcript of the transfer call (null if not available) Human-readable formatted transcript of the transfer call URL to download the transfer call recording (only included if "Include recording in webhook" is enabled and a recording exists) ISO 8601 timestamp when the transfer was initiated ISO 8601 timestamp when the transfer was completed ```json 200 Post-Call Webhook Request theme={null} { "id": 12345, "customer_phone": "+1234567890", "assistant_phone": "+1987654321", "duration": 125, "status": "completed", "extracted_variables": { "status": true, "summary": "Customer interested in product demo", "lead_quality": "high", "next_action": "schedule_demo" }, "input_variables": { "customer_name": "John Doe", "product_interest": "Pro Plan" }, "transcript": [ { "text": "Hello! This is Sarah from RepForce.ai. How are you today?", "type": "transcript", "sender": "bot", "timestamp": 1756812511.315143 }, { "text": "Hi, I'm doing well, thanks for calling.", "type": "transcript", "sender": "human", "timestamp": 1756812514.104436 }, { "text": "I'm calling to tell you about our new product features.", "type": "transcript", "sender": "bot", "timestamp": 1756812522.918859 }, { "text": "That sounds interesting, tell me more.", "type": "transcript", "sender": "human", "timestamp": 1756812525.234567 } ], "formatted_transcript": "AI: Hello! This is Sarah from RepForce.ai. How are you today?\nCustomer: Hi, I'm doing well, thanks for calling.\nAI: I'm calling to tell you about our new product features.\nCustomer: That sounds interesting, tell me more.", "recording_url": "https://repforce.ai/storage/recordings/call-12345.mp4", "created_at": "2025-01-15T10:30:00.000000Z", "finished_at": "2025-01-15T10:32:05.000000Z", "transfers": [ { "id": 12346, "status": "completed", "transfer_to": "+1555123456", "duration": 85, "carrier_cost": 0.0156, "transcript": null, "formatted_transcript": "", "created_at": "2025-01-15T10:31:00.000000Z", "finished_at": "2025-01-15T10:32:25.000000Z" } ], "lead": { "id": 789, "phone_number": "+1234567890", "variables": { "source": "website", "interest_level": "high" }, "status": "contacted", "call_tries": 2, "created_at": "2025-01-15T09:00:00.000000Z", "updated_at": "2025-01-15T10:32:05.000000Z", "campaign": { "id": 456, "name": "Product Demo Campaign", "status": "active", "allowed_hours_start_time": "09:00", "allowed_hours_end_time": "17:00", "allowed_days": ["monday", "tuesday", "wednesday", "thursday", "friday"], "max_calls_in_parallel": 5, "max_retries": 3, "retry_interval": 60, "created_at": "2025-01-15T08:00:00.000000Z", "updated_at": "2025-01-15T08:00:00.000000Z" } } } ``` ## Webhook Settings You can configure the following options for your post-call webhook: * **Send webhook only on completed**: Only send the webhook for successfully completed calls * **Include recording in webhook**: Include the `recording_url` field in the payload * **Custom variables**: Define custom variables that the AI should extract from the conversation ## Important Notes * The `customer_phone` and `assistant_phone` fields can be `null` if the information is not available * The `recording_url` field is only included if you have enabled "Include recording in webhook" in your [assistant settings](/ai-assistants/settings/post-call-actions#webhook-configuration) * The `lead` object is only included for calls that are part of a campaign * The `transfers` array is only included for calls that have transfer calls associated with them * The `extracted_variables` object will contain the variables you defined in your assistant's post-call schema configuration # Get WhatsApp Senders Source: https://docs.repforce.ai/api-reference/whatsapp/get-senders GET /user/whatsapp/senders List all WhatsApp Business senders for the authenticated user This endpoint returns a list of WhatsApp Business senders (phone numbers) configured for your account. Use this to retrieve sender IDs needed for sending messages. ### Query Parameters Filter senders by status. Default: `online`. Use `all` to return all senders regardless of status. ### Response Fields The unique identifier of the WhatsApp sender. Use this ID when sending messages. The sender's phone number in E.164 format (e.g., `+14155551234`) The WhatsApp Business display name (business name shown to recipients) The sender's current status: `online` or `offline` Meta's quality rating for this sender: `GREEN`, `YELLOW`, or `RED` The current messaging limit (number of unique recipients per 24 hours). `null` means unlimited. Human-readable messaging limit (e.g., `1,000 / 24hr`, `10,000 / 24hr`, or `Unlimited`) ```bash cURL theme={null} curl -X GET "https://app.repforce.ai/api/user/whatsapp/senders" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```bash Filter all senders theme={null} curl -X GET "https://app.repforce.ai/api/user/whatsapp/senders?status=all" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://app.repforce.ai/api/user/whatsapp/senders', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const data = await response.json(); console.log(data.data); // Array of senders ``` ```python Python theme={null} import requests response = requests.get( 'https://app.repforce.ai/api/user/whatsapp/senders', headers={'Authorization': 'Bearer YOUR_API_KEY'} ) senders = response.json()['data'] for sender in senders: print(f"{sender['display_name']}: {sender['phone_number']}") ``` ```json 200 Response theme={null} { "data": [ { "id": 12, "phone_number": "+14155551234", "display_name": "Acme Corp Support", "status": "online", "quality_rating": "GREEN", "messaging_limit": 10000, "messaging_limit_formatted": "10,000 / 24hr" }, { "id": 15, "phone_number": "+442071234567", "display_name": "Acme Corp Sales", "status": "online", "quality_rating": "GREEN", "messaging_limit": null, "messaging_limit_formatted": "Unlimited" } ] } ``` ```json 200 Empty Response theme={null} { "data": [] } ``` ### Notes * Only senders with status `online` are returned by default. Use `?status=all` to include offline senders. * Sender status is synced with Meta every 5 minutes automatically. * The `id` field is what you need to pass as `sender_id` when sending messages. * Quality rating affects your messaging limits. A `RED` rating may restrict your ability to send messages. # Get Templates Source: https://docs.repforce.ai/api-reference/whatsapp/get-templates GET /user/whatsapp/senders/{senderId}/templates List WhatsApp message templates for a specific sender This endpoint returns all message templates associated with a specific WhatsApp sender. Templates are required for initiating conversations or messaging users outside the 24-hour messaging window. ### Path Parameters The ID of the WhatsApp sender (obtained from the [Get Senders](/api-reference/whatsapp/get-senders) endpoint) ### Query Parameters Filter templates by approval status. Default: `approved`. Use `all` to return all templates regardless of status. ### Response Fields The unique identifier of the template. Use this when sending template messages. The template name as registered with Meta (e.g., `order_confirmation`, `appointment_reminder`) The template language code (e.g., `en`, `es`, `pt_BR`) The template category: `marketing`, `utility`, or `authentication` The approval status: `approved`, `pending`, or `rejected` The template body text, with variable placeholders shown as `{{1}}`, `{{2}}`, etc. List of variable names defined for the template. Empty array if the template has no variables. Whether this template requires variables to be provided when sending ### Error Responses `false` `Sender not found` `SENDER_NOT_FOUND` ```bash cURL theme={null} curl -X GET "https://app.repforce.ai/api/user/whatsapp/senders/12/templates" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```bash All templates (including pending/rejected) theme={null} curl -X GET "https://app.repforce.ai/api/user/whatsapp/senders/12/templates?status=all" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const senderId = 12; const response = await fetch( `https://app.repforce.ai/api/user/whatsapp/senders/${senderId}/templates`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const data = await response.json(); console.log(data.data); // Array of templates ``` ```python Python theme={null} import requests sender_id = 12 response = requests.get( f'https://app.repforce.ai/api/user/whatsapp/senders/{sender_id}/templates', headers={'Authorization': 'Bearer YOUR_API_KEY'} ) templates = response.json()['data'] for template in templates: print(f"{template['name']} ({template['language']}): {template['body_text']}") ``` ```json 200 Response theme={null} { "data": [ { "id": 45, "name": "appointment_reminder", "language": "en", "category": "utility", "status": "approved", "body_text": "Hi {{1}}, this is a reminder for your appointment on {{2}} at {{3}}. Reply YES to confirm or NO to reschedule.", "variables": ["customer_name", "date", "time"], "has_variables": true }, { "id": 46, "name": "welcome_message", "language": "en", "category": "marketing", "status": "approved", "body_text": "Welcome to Acme Corp! We're excited to have you. How can we help you today?", "variables": [], "has_variables": false } ] } ``` ```json 404 Sender Not Found theme={null} { "success": false, "error": "Sender not found", "error_code": "SENDER_NOT_FOUND" } ``` ### Notes * Only `approved` templates are returned by default. Templates with `pending` or `rejected` status cannot be used to send messages. * Template approval status is synced with Meta every 4 hours automatically. * Variables in `body_text` are shown as `{{1}}`, `{{2}}`, etc. The `variables` array provides human-readable names for each placeholder. * Templates are required when messaging a user for the first time or outside the 24-hour messaging window. # Send Freeform Message Source: https://docs.repforce.ai/api-reference/whatsapp/send-freeform POST /user/whatsapp/send-freeform Send a free-text WhatsApp message within an active 24-hour session This endpoint sends a freeform (free-text) WhatsApp message to a recipient. Unlike template messages, freeform messages can contain any text but **require an active 24-hour messaging window** — meaning the recipient must have sent a message to your WhatsApp sender within the last 24 hours. Freeform messages can only be sent during an active 24-hour messaging window. If the session has expired, you must send a [template message](/api-reference/whatsapp/send-template) first to re-initiate the conversation. Use the [Session Status](/api-reference/whatsapp/session-status) endpoint to check if a session is active. This endpoint is rate-limited to **5 requests per second** per user. ### Request Body The ID of the WhatsApp sender to send from (obtained from the [Get Senders](/api-reference/whatsapp/get-senders) endpoint) The recipient's phone number in international format (e.g., `+1234567890`) The message content to send (max 4096 characters) ### Response Fields Whether the message was sent successfully The ID of the conversation associated with this message The ID of the conversation message record The ID of the WhatsApp message record The Twilio message SID for tracking delivery Updated session status after sending the message Whether the 24-hour messaging window is currently open Whether freeform messages can be sent right now Whether a template message is required Human-readable description of the session state Minutes remaining in the 24-hour window ISO 8601 timestamp when the session expires ### Error Responses `false` `Insufficient balance. Please top up your account.` `INSUFFICIENT_BALANCE` `false` Message indicating the 24-hour messaging window has expired `SESSION_EXPIRED` Current session status with `is_open`, `can_send_freeform`, `requires_template`, and `message` fields `false` `Sender not found or does not belong to you` `SENDER_NOT_FOUND` `false` Message indicating the sender is currently offline `SENDER_OFFLINE` ```bash cURL theme={null} curl -X POST "https://app.repforce.ai/api/user/whatsapp/send-freeform" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sender_id": 12, "recipient_phone": "+1234567890", "message": "Thank you for your inquiry! Our team will review your request and get back to you within 2 hours." }' ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://app.repforce.ai/api/user/whatsapp/send-freeform', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ sender_id: 12, recipient_phone: '+1234567890', message: 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.' }) } ); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests response = requests.post( 'https://app.repforce.ai/api/user/whatsapp/send-freeform', headers={ 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, json={ 'sender_id': 12, 'recipient_phone': '+1234567890', 'message': 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.' } ) print(response.json()) ``` ```json 200 Success theme={null} { "success": true, "conversation_id": 1234, "message_id": 567, "whatsapp_message_id": 890, "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "session_status": { "is_open": true, "can_send_freeform": true, "requires_template": false, "message": "Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.", "minutes_remaining": 1425, "expires_at": "2026-02-25T10:30:00+00:00" } } ``` ```json 402 Insufficient Balance theme={null} { "success": false, "error": "Insufficient balance. Please top up your account.", "error_code": "INSUFFICIENT_BALANCE" } ``` ```json 403 Session Expired theme={null} { "success": false, "error": "The 24-hour messaging window is closed. Customer must reply first, or use a template message.", "error_code": "SESSION_EXPIRED", "session_status": { "is_open": false, "can_send_freeform": false, "requires_template": true, "message": "Session expired. Send a template or wait for customer to reply.", "expired_at": "2026-02-23T10:30:00+00:00" } } ``` ```json 404 Sender Not Found theme={null} { "success": false, "error": "Sender not found or does not belong to you", "error_code": "SENDER_NOT_FOUND" } ``` ```json 422 Invalid Phone theme={null} { "success": false, "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).", "error_code": "INVALID_PHONE" } ``` ```json 503 Sender Offline theme={null} { "success": false, "error": "Sender is not online. Current status: Offline", "error_code": "SENDER_OFFLINE" } ``` ### 24-Hour Messaging Window WhatsApp enforces a **24-hour messaging window** policy: 1. When a customer sends a message to your WhatsApp Business number, a 24-hour window opens. 2. During this window, you can send freeform messages without restrictions. 3. After the window expires, you must use a [template message](/api-reference/whatsapp/send-template) to re-initiate the conversation. 4. Each new customer message resets the 24-hour timer. Use the [Session Status](/api-reference/whatsapp/session-status) endpoint to check whether a session is active before attempting to send a freeform message. ### Notes * Maximum message length is **4,096 characters** (WhatsApp limit). * The sender must be `online`. Offline senders return a `503` error. * Message costs are automatically deducted from your account balance. * Rate limit: 5 requests per second per user. # Send Template Message Source: https://docs.repforce.ai/api-reference/whatsapp/send-template POST /user/whatsapp/send Send a WhatsApp message using an approved template This endpoint sends a WhatsApp message using a pre-approved template. Template messages are required when initiating a conversation with a user for the first time or when messaging outside the 24-hour messaging window. This endpoint is rate-limited to **5 requests per second** per user. ### Request Body The ID of the WhatsApp sender to send from (obtained from the [Get Senders](/api-reference/whatsapp/get-senders) endpoint) The ID of the message template to use (obtained from the [Get Templates](/api-reference/whatsapp/get-templates) endpoint) The recipient's phone number in international format (e.g., `+1234567890`) The recipient's name, max 255 characters (used for conversation tracking and CRM purposes) Key-value pairs for template variables. Keys should match the variable names from the template. If the template has variables `{{1}}`, `{{2}}`, etc., provide them as `{"1": "value1", "2": "value2"}` or using the named keys from the template's `variables` array. Value for the first template variable Value for the second template variable ### Response Fields Whether the message was sent successfully The ID of the conversation (new or existing) associated with this message The ID of the conversation message record The ID of the WhatsApp message record The Twilio message SID for tracking delivery The initial message delivery status (e.g., `queued`, `sent`) ### Error Responses `false` `Insufficient balance. Please top up your account.` `INSUFFICIENT_BALANCE` `false` `Sender not found or does not belong to you` or `Template not found or does not belong to this sender` `SENDER_NOT_FOUND` or `TEMPLATE_NOT_FOUND` `false` Detailed error message One of: `SENDER_OFFLINE`, `TEMPLATE_NOT_APPROVED`, `TEMPLATE_NOT_SYNCED`, `TEMPLATE_MISMATCH`, `NO_ASSISTANT_CONFIGURED`, `INVALID_PHONE`, `MESSAGING_LIMIT_UNAVAILABLE`, `VOICE_CALL_LIMIT_NOT_MET`, `TWILIO_ERROR_{code}`, `UNKNOWN_ERROR` ```bash cURL theme={null} curl -X POST "https://app.repforce.ai/api/user/whatsapp/send" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sender_id": 12, "template_id": 45, "recipient_phone": "+1234567890", "recipient_name": "John Doe", "variables": { "1": "John", "2": "January 15, 2026", "3": "2:00 PM" } }' ``` ```bash Template without variables theme={null} curl -X POST "https://app.repforce.ai/api/user/whatsapp/send" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sender_id": 12, "template_id": 46, "recipient_phone": "+1234567890" }' ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://app.repforce.ai/api/user/whatsapp/send', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ sender_id: 12, template_id: 45, recipient_phone: '+1234567890', recipient_name: 'John Doe', variables: { '1': 'John', '2': 'January 15, 2026', '3': '2:00 PM' } }) } ); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests response = requests.post( 'https://app.repforce.ai/api/user/whatsapp/send', headers={ 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, json={ 'sender_id': 12, 'template_id': 45, 'recipient_phone': '+1234567890', 'recipient_name': 'John Doe', 'variables': { '1': 'John', '2': 'January 15, 2026', '3': '2:00 PM' } } ) print(response.json()) ``` ```json 200 Success theme={null} { "success": true, "conversation_id": 1234, "message_id": 567, "whatsapp_message_id": 890, "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "status": "queued" } ``` ```json 402 Insufficient Balance theme={null} { "success": false, "error": "Insufficient balance. Please top up your account.", "error_code": "INSUFFICIENT_BALANCE" } ``` ```json 404 Sender Not Found theme={null} { "success": false, "error": "Sender not found or does not belong to you", "error_code": "SENDER_NOT_FOUND" } ``` ```json 404 Template Not Found theme={null} { "success": false, "error": "Template not found or does not belong to this sender", "error_code": "TEMPLATE_NOT_FOUND" } ``` ```json 422 Template Not Approved theme={null} { "success": false, "error": "Template is not approved. Current status: pending", "error_code": "TEMPLATE_NOT_APPROVED" } ``` ```json 422 Invalid Phone theme={null} { "success": false, "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).", "error_code": "INVALID_PHONE" } ``` ```json 422 Sender Offline theme={null} { "success": false, "error": "Sender is not online. Current status: Offline", "error_code": "SENDER_OFFLINE" } ``` ### Notes * Template messages must use **approved** templates. Templates with `pending` or `rejected` status will fail. * The sender must be `online`. Offline senders cannot send messages. * Message costs are automatically deducted from your account balance (credits for tenant users, minutes for direct users). * After sending a template message, a 24-hour messaging window opens. During this window, you can send [freeform messages](/api-reference/whatsapp/send-freeform) without needing a template. * If a conversation already exists with the recipient, the message is added to the existing conversation. * Rate limit: 5 requests per second per user. # Get Session Status Source: https://docs.repforce.ai/api-reference/whatsapp/session-status GET /user/whatsapp/session-status Check the 24-hour messaging window status for a WhatsApp conversation This endpoint checks whether an active 24-hour messaging window exists between your WhatsApp sender and a specific recipient. Use this to determine whether you can send [freeform messages](/api-reference/whatsapp/send-freeform) or need to use a [template message](/api-reference/whatsapp/send-template). ### Query Parameters The ID of the WhatsApp sender (obtained from the [Get Senders](/api-reference/whatsapp/get-senders) endpoint) The recipient's phone number in international format (e.g., `+1234567890`) ### Response Fields Whether the request was successful Whether a conversation exists with this recipient The conversation ID (only present when `has_conversation` is `true`) The customer's name if available (only present when `has_conversation` is `true`) ISO 8601 timestamp of the customer's last message (only present when `has_conversation` is `true`) Whether the 24-hour messaging window is currently open Whether freeform (non-template) messages can be sent right now Whether a template message is required to message this recipient Human-readable description of the current session state Minutes remaining in the 24-hour window (only present when session is open) ISO 8601 timestamp when the session expires (present when session is open or no customer message exists) ISO 8601 timestamp when the session expired (only present when session has expired) ### Error Responses `false` `Sender not found` `SENDER_NOT_FOUND` ```bash cURL theme={null} curl -X GET "https://app.repforce.ai/api/user/whatsapp/session-status?sender_id=12&recipient_phone=+1234567890" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const params = new URLSearchParams({ sender_id: '12', recipient_phone: '+1234567890' }); const response = await fetch( `https://app.repforce.ai/api/user/whatsapp/session-status?${params}`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const data = await response.json(); if (data.session_status.can_send_freeform) { console.log('Session is active — freeform messages allowed'); } else { console.log('Session expired — use a template message'); } ``` ```python Python theme={null} import requests response = requests.get( 'https://app.repforce.ai/api/user/whatsapp/session-status', headers={'Authorization': 'Bearer YOUR_API_KEY'}, params={ 'sender_id': 12, 'recipient_phone': '+1234567890' } ) data = response.json() session = data['session_status'] if session['can_send_freeform']: print('Session is active — freeform messages allowed') else: print('Session expired — use a template message') ``` ```json 200 Active Session theme={null} { "success": true, "has_conversation": true, "conversation_id": 1234, "customer_name": "John Doe", "last_customer_message_at": "2026-02-24T10:30:00+00:00", "session_status": { "is_open": true, "can_send_freeform": true, "requires_template": false, "message": "Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.", "minutes_remaining": 1425, "expires_at": "2026-02-25T10:30:00+00:00" } } ``` ```json 200 Expired Session theme={null} { "success": true, "has_conversation": true, "conversation_id": 1234, "customer_name": "John Doe", "last_customer_message_at": "2026-02-22T14:00:00+00:00", "session_status": { "is_open": false, "can_send_freeform": false, "requires_template": true, "message": "Session expired. Send a template or wait for customer to reply.", "expired_at": "2026-02-23T14:00:00+00:00" } } ``` ```json 200 No Conversation theme={null} { "success": true, "has_conversation": false, "session_status": { "is_open": false, "can_send_freeform": false, "requires_template": true, "message": "No conversation exists with this recipient. Send a template message first." } } ``` ```json 404 Sender Not Found theme={null} { "success": false, "error": "Sender not found", "error_code": "SENDER_NOT_FOUND" } ``` ### Typical Workflow Use this endpoint as part of a message-sending flow: 1. **Check session status** before sending a message 2. If `can_send_freeform` is `true` → use [Send Freeform Message](/api-reference/whatsapp/send-freeform) 3. If `requires_template` is `true` → use [Send Template Message](/api-reference/whatsapp/send-template) ### Notes * The 24-hour window is based on the customer's last inbound message timestamp. * Each new customer message resets the 24-hour timer. * This endpoint does not consume any balance — it's a read-only status check. # Building Flows Source: https://docs.repforce.ai/automation-platform/building-flows Flow consists of two parts, trigger and actions ## Trigger The flow's starting point determines its frequency of execution. There are various types of triggers available, such as Schedule Trigger, Webhook Trigger, or Event Trigger based on specific service. ## Action Actions come after the flow and control what occurs when the flow is activated, like running code or communicating with other services. In real-life scenario: Flow Parts # Common Integrations Source: https://docs.repforce.ai/automation-platform/calls-related/common-integrations Explore popular integrations with Google Sheets, calendars, CRMs, and notification tools Below are some popular tools you can connect to RepForce.ai using the built-in no-code platform or direct integrations: ## 1. Google Sheets * **Import Leads**: Poll a sheet of phone numbers for an outbound campaign. * **Log Call Results**: Append transcripts or call summaries to a "Call History" sheet. ## 2. Calendars (Cal.com, Google Calendar, etc.) * **Appointment Scheduling**: The AI can suggest free slots, then create events. * **Reminders**: If a call is about an upcoming appointment, the AI can confirm or reschedule. ## 3. HubSpot / CRMs * **Lead Data**: Post-call info can be saved to a contact record. * **Status Updates**: Change lead status to "Interested" or "Requires Follow-Up" automatically. ## 4. Slack / Email Notifications * **Immediate Alerts**: If a user says "I want to cancel" or "I want to buy," trigger a Slack ping. * **Daily Summary**: Email your team a daily summary of calls, outcomes, and new leads. ## 5. Others (Facebook Leads, etc.) * Some advanced users integrate with Facebook Lead Ads or other marketing platforms to feed real-time leads into an RepForce.ai outbound campaign. *** **Tip:** In the RepForce.ai automation editor, you'll see pre-built blocks for many popular tools. If something's missing, you can often use **Webhooks** or the **API** to connect. # RepForce.ai Tool Source: https://docs.repforce.ai/automation-platform/calls-related/platform-tool Learn how to use RepForce.ai triggers and actions in your AI calling flows # RepForce.ai Tool The RepForce.ai tool is the core component that connects your AI calling system with automation flows. It enables real-time data exchange between your AI assistants and business systems, allowing for personalized conversations and automated follow-ups. You can find the RepForce.ai tool prominently displayed at the top of the searching sidebar when looking for either triggers or actions. ## Triggers ### Call Ended RepForce.ai Call Ended Trigger The Call Ended trigger activates immediately after an AI call completes, providing comprehensive data about the interaction: * Complete conversation transcript with timestamps * AI assistant responses and decisions * Call duration and technical metadata * Customer information and phone number * Call outcome and sentiment analysis * Variables set during the conversation #### Configuration 1. Select "Call Ended" as your trigger 2. Choose specific AI assistant to monitor 3. Configure variable mapping ### Inbound Call Variable Injection This powerful trigger activates before your AI assistant picks up an inbound call, allowing you to: * Fetch and inject real-time customer data * Customize AI behavior based on context * Set conversation parameters * Define AI personality traits * Provide business logic variables #### Configuration 1. Select "Inbound Call" as your trigger 2. Define required variables for AI context ## Actions ### Add Lead to Campaign RepForce.ai Action This action helps manage your AI calling campaigns by: * Creating new leads from extenal tools like Sheets, Hubspot, Facebook leads * Assigning leads to specific AI campaigns * Adding context for future calls #### Configuration 1. Select target AI campaign 2. Map contact details from trigger data 3. Add custom attributes for AI context ### Return Variables This action is crucial for inbound calls, returning context that gets injected into the AI's prompt: * Customer profile and preferences * Conversation history summary * Business rules and constraints * Custom AI behavior flags * Dynamic response templates #### Configuration 1. Structure response JSON 2. Map customer data to variables 3. Set AI conversation parameters 4. Configure timeout handling ## Example Usage ### Post-Call Lead Management ```javascript theme={null} Trigger: AI Call Ended ↓ Extract conversation insights ↓ Update Hubspot record ↓ Add to follow-up campaign if qualified ``` ### Intelligent Inbound Routing ```javascript theme={null} Trigger: Inbound Call to AI ↓ Fetch customer profile from CRM ↓ Get interaction history ↓ Return enriched context for AI prompt ``` ## Best Practices 1. **Variable Injection Performance** * Keep processing under 2 seconds * Set sensible defaults 2. **Data Structure** * Follow AI prompt requirements * Validate all variables * Structure nested objects clearly * Document custom fields 3. **Error Handling** * Provide fallback values * Log injection failures * Monitor response times * Handle missing data gracefully # Sending SMS Source: https://docs.repforce.ai/automation-platform/calls-related/sms-capabilities Learn how to send SMS messages using the automation platform and SMS-capable numbers If your rented or custom-provisioned number supports SMS capabilities, you can leverage the automation platform to send text messages: ## 1. SMS Actions * Send confirmation messages after calls * Deliver follow-up information or links * Send appointment reminders * Provide quick updates or notifications ## 2. Configuration 1. Ensure your phone number is SMS-capable 2. Use the "Send SMS" action in your automation flow 3. Configure message template and variables 4. Set up triggers (e.g., after call completion) ## 3. Best Practices * Keep messages concise and professional * Include opt-out instructions if required by local laws * Test SMS delivery before large campaigns * Monitor delivery rates and costs *** **Note:** SMS capability depends on your phone number's region and type. Contact support to confirm if your number supports texting. # Debugging Runs Source: https://docs.repforce.ai/automation-platform/debugging-runs Ensuring your business automations are running properly You can monitor each run that results from an enabled flow: 1. Go to the Dashboard, click on **Runs**. 2. Find the run that you're looking for, and click on it. 3. You will see the builder in a view-only mode, each step will show a ✅ or a ❌ to indicate its execution status. 4. Click on any of these steps, you will see the **input** and **output** in the **Run Details** panel. The debugging experience looks like this: Debugging Business Automations # Introduction Source: https://docs.repforce.ai/automation-platform/introduction Learn How to Automate Your AI Call Workflows with RepForce.ai. # Automation Platform The RepForce.ai Automation Platform helps you create powerful AI call automation workflows without coding. Build flows that enhance your AI calling system by processing variables before calls, handling post-call actions, and creating seamless integrations with your existing tools. Flow Builder ## Key Features ### AI Call-Based Triggers 1. **Call Ended Trigger** * Activates immediately when an AI call completes * Access full conversation transcript and AI responses * Use call duration, status, and detailed metadata * Perfect for post-call automation like CRM updates * Trigger follow-up actions based on call outcomes 2. **Inbound Call Variable Injection** * Triggers before AI assistant picks up the call * Enriches AI context with real-time customer data * Customizes AI behavior based on caller information * Returns variables that get injected into AI prompts * Enables personalized conversation flows ### Essential Actions 1. **Hubspot Integration** * Update contact records with call outcomes * Create new contacts from inbound calls * Sync conversation insights to CRM * Track AI interaction history * Automate lead qualification 2. **Campaign Management** * Add qualified leads to AI calling campaigns * Schedule AI follow-up calls * Manage call priorities based on outcomes * Track conversion rates per campaign * Automate campaign assignments 3. **External Systems** * Send post-call summary emails * Update spreadsheets with call data * Trigger webhooks for custom integrations * Connect with your business tools * Automate multi-step workflows ## How It Works 1. **Choose Your Call Trigger** * "Call Ended" for post-conversation automation * "Inbound Call" for real-time AI context injection 2. **Configure Call Variables** * Map AI conversation data and transcripts * Access caller details and history * Define AI routing logic * Set up custom conversation variables 3. **Add Smart Actions** * Update CRM with call outcomes * Send automated notifications * Schedule follow-up activities * Return enriched context to AI ## Example Use Cases ### Intelligent CRM Update ```javascript theme={null} Trigger: AI Call Ended ↓ Process Conversation Insights ↓ Update Hubspot Contact ↓ Schedule Next AI Interaction ``` ### Smart Inbound Call Handling ```javascript theme={null} Trigger: Inbound Call to AI ↓ Lookup Customer in Hubspot ↓ Return Enriched Context ↓ AI Assistant Personalizes Conversation ``` # Technical limits Source: https://docs.repforce.ai/automation-platform/known-limits Technical limits for flows execution ### Overview ### Flow Limits * **Execution Time**: Each flow has a maximum execution time of **600 seconds (10 minutes)**. Flows exceeding this limit will be marked as a timeout. * **Memory Usage**: During execution, a flow should not use more than **128 MB of RAM**. ### File Storage Limits * **Maximum File Size**: 10 MB ### Data Storage Limits Some pieces utilize the built-in key store, such as the Store Piece and Queue Piece. The storage limits are as follows: * **Maximum Key Length**: 128 characters * **Maximum Value Size**: 512 KB # Passing Data Source: https://docs.repforce.ai/automation-platform/passing-data Using data from previous steps in the current one ## Data flow Any flow is a vertical diagram that **starts with a trigger step** followed by **any number of action steps**. Steps are connected vertically. Data flows from parent steps to the children. Children steps have access to the output data of the parent steps. ## Example Steps