# Agent Chat Completion (GHL-Safe) Source: https://docs.assistable.ai/api-reference/agent-chat-completion-ghl-safe /api-reference/chat-api.json post /v2/ghl-chat-completion # Get an alert Source: https://docs.assistable.ai/api-reference/alerts/get-an-alert /direct/openapi.json get /v3/alerts/{id} Requires scope `alerts:read`. # List alerts Source: https://docs.assistable.ai/api-reference/alerts/list-alerts /direct/openapi.json get /v3/alerts Requires scope `alerts:list`. # Update an alert's resolution status or note Source: https://docs.assistable.ai/api-reference/alerts/update-an-alerts-resolution-status-or-note /direct/openapi.json patch /v3/alerts/{id} Requires scope `alerts:update`. # Create an appointment Source: https://docs.assistable.ai/api-reference/appointments/create-an-appointment /v3/openapi.json post /v3/appointments Requires scope `appointments:create`. # Get an appointment Source: https://docs.assistable.ai/api-reference/appointments/get-an-appointment /v3/openapi.json get /v3/appointments/{id} Requires scope `appointments:read`. # List appointments in a date range Source: https://docs.assistable.ai/api-reference/appointments/list-appointments-in-a-date-range /v3/openapi.json get /v3/appointments Requires scope `appointments:list`. # Update an appointment Source: https://docs.assistable.ai/api-reference/appointments/update-an-appointment /v3/openapi.json patch /v3/appointments/{id} Requires scope `appointments:update`. # Archive Assistant Source: https://docs.assistable.ai/api-reference/archive-assistant /api-reference/assistant-api.json delete /v2/delete-assistant # Assign assistants to a folder Source: https://docs.assistable.ai/api-reference/assistant-folders/assign-assistants-to-a-folder /direct/openapi.json post /v3/assistant-folders/{id}/assign Requires scope `assistants:update`. # Create an assistant folder Source: https://docs.assistable.ai/api-reference/assistant-folders/create-an-assistant-folder /direct/openapi.json post /v3/assistant-folders Requires scope `assistants:create`. # Delete (archive) an assistant folder Source: https://docs.assistable.ai/api-reference/assistant-folders/delete-archive-an-assistant-folder /direct/openapi.json delete /v3/assistant-folders/{id} Requires scope `assistants:delete`. # List assistant folders Source: https://docs.assistable.ai/api-reference/assistant-folders/list-assistant-folders /direct/openapi.json get /v3/assistant-folders Requires scope `assistants:list`. # Remove assistants from a folder Source: https://docs.assistable.ai/api-reference/assistant-folders/remove-assistants-from-a-folder /direct/openapi.json post /v3/assistant-folders/{id}/remove Requires scope `assistants:update`. # Update an assistant folder Source: https://docs.assistable.ai/api-reference/assistant-folders/update-an-assistant-folder /direct/openapi.json patch /v3/assistant-folders/{id} Requires scope `assistants:update`. # Add a note to an assistant Source: https://docs.assistable.ai/api-reference/assistants/add-a-note-to-an-assistant /direct/openapi.json post /v3/assistants/{id}/notes Requires scope `assistants:create`. # Archive an assistant Source: https://docs.assistable.ai/api-reference/assistants/archive-an-assistant /direct/openapi.json post /v3/assistants/{id}/archive Requires scope `assistants:update`. # Create an assistant Source: https://docs.assistable.ai/api-reference/assistants/create-an-assistant /direct/openapi.json post /v3/assistants Requires scope `assistants:create`. # Delete an assistant note Source: https://docs.assistable.ai/api-reference/assistants/delete-an-assistant-note /direct/openapi.json delete /v3/assistants/{id}/notes/{note_id} Requires scope `assistants:delete`. # Delete (soft) an assistant Source: https://docs.assistable.ai/api-reference/assistants/delete-soft-an-assistant /direct/openapi.json delete /v3/assistants/{id} Requires scope `assistants:delete`. # Duplicate an assistant Source: https://docs.assistable.ai/api-reference/assistants/duplicate-an-assistant /direct/openapi.json post /v3/assistants/{id}/duplicate Requires scope `assistants:create`. # Get an assistant Source: https://docs.assistable.ai/api-reference/assistants/get-an-assistant /direct/openapi.json get /v3/assistants/{id} Requires scope `assistants:read`. # List assistant notes Source: https://docs.assistable.ai/api-reference/assistants/list-assistant-notes /direct/openapi.json get /v3/assistants/{id}/notes Requires scope `assistants:read`. # List assistant versions Source: https://docs.assistable.ai/api-reference/assistants/list-assistant-versions /direct/openapi.json get /v3/assistants/{id}/versions Requires scope `assistants:read`. # List assistants Source: https://docs.assistable.ai/api-reference/assistants/list-assistants /direct/openapi.json get /v3/assistants Requires scope `assistants:list`. # Revert an assistant to a version Source: https://docs.assistable.ai/api-reference/assistants/revert-an-assistant-to-a-version /direct/openapi.json post /v3/assistants/{id}/versions/{version_id}/revert Requires scope `assistants:update`. Note: reverting does not restore voice_settings (greeting mode, opening messages, or voicemail behavior) — those keep their current values. # Unarchive an assistant Source: https://docs.assistable.ai/api-reference/assistants/unarchive-an-assistant /direct/openapi.json post /v3/assistants/{id}/unarchive Requires scope `assistants:update`. # Update an assistant Source: https://docs.assistable.ai/api-reference/assistants/update-an-assistant /direct/openapi.json patch /v3/assistants/{id} Requires scope `assistants:update`. # Call stats for the subaccount Source: https://docs.assistable.ai/api-reference/calls/call-stats-for-the-subaccount /direct/openapi.json get /v3/calls/stats Requires scope `calls:read`. # Get a call (rich detail) Source: https://docs.assistable.ai/api-reference/calls/get-a-call-rich-detail /direct/openapi.json get /v3/calls/{id} Requires scope `calls:read`. # List call history Source: https://docs.assistable.ai/api-reference/calls/list-call-history /direct/openapi.json get /v3/calls Requires scope `calls:list`. # Place an AI voice call Source: https://docs.assistable.ai/api-reference/calls/place-an-ai-voice-call /direct/openapi.json post /v3/calls Requires scope `calls:create`. # Run an AI chat completion on a conversation Source: https://docs.assistable.ai/api-reference/chat/run-an-ai-chat-completion-on-a-conversation /direct/openapi.json post /v3/chat/completions Requires scope `chat:create`. # Add a note to a contact Source: https://docs.assistable.ai/api-reference/contacts/add-a-note-to-a-contact /direct/openapi.json post /v3/contacts/{id}/notes Requires scope `contacts:create`. # Create a contact Source: https://docs.assistable.ai/api-reference/contacts/create-a-contact /direct/openapi.json post /v3/contacts Requires scope `contacts:create`. # Delete a contact note Source: https://docs.assistable.ai/api-reference/contacts/delete-a-contact-note /direct/openapi.json delete /v3/contacts/{id}/notes/{note_id} Requires scope `contacts:delete`. # Delete (archive) a contact Source: https://docs.assistable.ai/api-reference/contacts/delete-archive-a-contact /direct/openapi.json delete /v3/contacts/{id} Requires scope `contacts:delete`. # Get a contact Source: https://docs.assistable.ai/api-reference/contacts/get-a-contact /direct/openapi.json get /v3/contacts/{id} Requires scope `contacts:read`. # List contact interactions Source: https://docs.assistable.ai/api-reference/contacts/list-contact-interactions /direct/openapi.json get /v3/contacts/{id}/interactions Requires scope `contacts:read`. # List contact notes Source: https://docs.assistable.ai/api-reference/contacts/list-contact-notes /direct/openapi.json get /v3/contacts/{id}/notes Requires scope `contacts:read`. # List contacts Source: https://docs.assistable.ai/api-reference/contacts/list-contacts /direct/openapi.json get /v3/contacts Requires scope `contacts:list`. # Permanently delete a contact Source: https://docs.assistable.ai/api-reference/contacts/permanently-delete-a-contact /direct/openapi.json post /v3/contacts/{id}/permanent-delete Requires scope `contacts:delete`. # Update a contact Source: https://docs.assistable.ai/api-reference/contacts/update-a-contact /direct/openapi.json patch /v3/contacts/{id} Requires scope `contacts:update`. # Conversation stats for the subaccount Source: https://docs.assistable.ai/api-reference/conversations/conversation-stats-for-the-subaccount /direct/openapi.json get /v3/conversations/stats Requires scope `conversations:read`. # Delete (soft) a conversation Source: https://docs.assistable.ai/api-reference/conversations/delete-soft-a-conversation /direct/openapi.json delete /v3/conversations/{id} Requires scope `conversations:delete`. # Get a conversation Source: https://docs.assistable.ai/api-reference/conversations/get-a-conversation /direct/openapi.json get /v3/conversations/{id} Requires scope `conversations:read`. # List calls for a conversation Source: https://docs.assistable.ai/api-reference/conversations/list-calls-for-a-conversation /direct/openapi.json get /v3/conversations/{id}/calls Requires scope `conversations:read`. # List conversations Source: https://docs.assistable.ai/api-reference/conversations/list-conversations /direct/openapi.json get /v3/conversations Requires scope `conversations:list`. # Update a conversation Source: https://docs.assistable.ai/api-reference/conversations/update-a-conversation /direct/openapi.json patch /v3/conversations/{id} Requires scope `conversations:update`. # Create Assistant Source: https://docs.assistable.ai/api-reference/create-assistant /api-reference/assistant-api.json post /v2/create-assistant # Create Flow Source: https://docs.assistable.ai/api-reference/create-flow /api-reference/assistant-api.json post /v2/create-flow Creates a new flow for the specified location # Create Message Source: https://docs.assistable.ai/api-reference/create-message /api-reference/chat-api.json post /v2/create-message # Create a flow Source: https://docs.assistable.ai/api-reference/flows/create-a-flow /direct/openapi.json post /v3/flows Requires scope `flows:create`. # Get Assistant Source: https://docs.assistable.ai/api-reference/get-assistant /api-reference/assistant-api.json get /v2/get-assistant # Get Messages Source: https://docs.assistable.ai/api-reference/get-messages /api-reference/chat-api.json get /v2/get-conversation # Add a file source Source: https://docs.assistable.ai/api-reference/knowledge-base/add-a-file-source /direct/openapi.json post /v3/knowledge-bases/{id}/sources/file Requires scope `knowledge:create`. # Add a text source Source: https://docs.assistable.ai/api-reference/knowledge-base/add-a-text-source /direct/openapi.json post /v3/knowledge-bases/{id}/sources/text Requires scope `knowledge:create`. # Add a URL source Source: https://docs.assistable.ai/api-reference/knowledge-base/add-a-url-source /direct/openapi.json post /v3/knowledge-bases/{id}/sources/url Requires scope `knowledge:create`. # Add an FAQ source Source: https://docs.assistable.ai/api-reference/knowledge-base/add-an-faq-source /direct/openapi.json post /v3/knowledge-bases/{id}/sources/faq Requires scope `knowledge:create`. # Archive a knowledge base Source: https://docs.assistable.ai/api-reference/knowledge-base/archive-a-knowledge-base /direct/openapi.json delete /v3/knowledge-bases/{id} Requires scope `knowledge:delete`. # Assign a knowledge base to an assistant Source: https://docs.assistable.ai/api-reference/knowledge-base/assign-a-knowledge-base-to-an-assistant /direct/openapi.json post /v3/knowledge-bases/{id}/assign Requires scope `knowledge:update`. # Create a knowledge base Source: https://docs.assistable.ai/api-reference/knowledge-base/create-a-knowledge-base /direct/openapi.json post /v3/knowledge-bases Requires scope `knowledge:create`. # Create a query training Source: https://docs.assistable.ai/api-reference/knowledge-base/create-a-query-training /direct/openapi.json post /v3/knowledge-bases/{id}/query-trainings Requires scope `knowledge:create`. # Delete a query training Source: https://docs.assistable.ai/api-reference/knowledge-base/delete-a-query-training /direct/openapi.json delete /v3/knowledge-bases/{id}/query-trainings/{training_id} Requires scope `knowledge:delete`. # Delete a source Source: https://docs.assistable.ai/api-reference/knowledge-base/delete-a-source /direct/openapi.json delete /v3/knowledge-bases/{id}/sources/{source_id} Requires scope `knowledge:delete`. # Disable voice for a knowledge base Source: https://docs.assistable.ai/api-reference/knowledge-base/disable-voice-for-a-knowledge-base /direct/openapi.json post /v3/knowledge-bases/{id}/voice/disable Requires scope `knowledge:update`. # Enable voice for a knowledge base Source: https://docs.assistable.ai/api-reference/knowledge-base/enable-voice-for-a-knowledge-base /direct/openapi.json post /v3/knowledge-bases/{id}/voice/enable Requires scope `knowledge:update`. # Get a knowledge base (with sources) Source: https://docs.assistable.ai/api-reference/knowledge-base/get-a-knowledge-base-with-sources /direct/openapi.json get /v3/knowledge-bases/{id} Requires scope `knowledge:read`. # List an assistant's knowledge base ids Source: https://docs.assistable.ai/api-reference/knowledge-base/list-an-assistants-knowledge-base-ids /direct/openapi.json get /v3/assistants/{id}/knowledge-bases Requires scope `knowledge:read`. # List knowledge bases Source: https://docs.assistable.ai/api-reference/knowledge-base/list-knowledge-bases /direct/openapi.json get /v3/knowledge-bases Requires scope `knowledge:list`. # List query trainings Source: https://docs.assistable.ai/api-reference/knowledge-base/list-query-trainings /direct/openapi.json get /v3/knowledge-bases/{id}/query-trainings Requires scope `knowledge:read`. # Remove a knowledge base from an assistant Source: https://docs.assistable.ai/api-reference/knowledge-base/remove-a-knowledge-base-from-an-assistant /direct/openapi.json post /v3/knowledge-bases/{id}/remove Requires scope `knowledge:update`. # Rename a source Source: https://docs.assistable.ai/api-reference/knowledge-base/rename-a-source /direct/openapi.json patch /v3/knowledge-bases/{id}/sources/{source_id} Requires scope `knowledge:update`. # Toggle a query training active flag Source: https://docs.assistable.ai/api-reference/knowledge-base/toggle-a-query-training-active-flag /direct/openapi.json post /v3/knowledge-bases/{id}/query-trainings/{training_id}/toggle Requires scope `knowledge:update`. # Update a knowledge base Source: https://docs.assistable.ai/api-reference/knowledge-base/update-a-knowledge-base /direct/openapi.json patch /v3/knowledge-bases/{id} Requires scope `knowledge:update`. # Update a query training Source: https://docs.assistable.ai/api-reference/knowledge-base/update-a-query-training /direct/openapi.json patch /v3/knowledge-bases/{id}/query-trainings/{training_id} Requires scope `knowledge:update`. # Make AI Call (GHL-Safe) Source: https://docs.assistable.ai/api-reference/make-ai-call-ghl-safe /api-reference/calling-api.json post /v2/ghl/make-call # Create a message Source: https://docs.assistable.ai/api-reference/messages/create-a-message /direct/openapi.json post /v3/messages Requires scope `messages:create`. # List messages in a conversation Source: https://docs.assistable.ai/api-reference/messages/list-messages-in-a-conversation /direct/openapi.json get /v3/conversations/{id}/messages Requires scope `messages:list`. # Create a monitor rule Source: https://docs.assistable.ai/api-reference/monitor-rules/create-a-monitor-rule /direct/openapi.json post /v3/monitor-rules Requires scope `monitor-rules:create`. # Delete a monitor rule Source: https://docs.assistable.ai/api-reference/monitor-rules/delete-a-monitor-rule /direct/openapi.json delete /v3/monitor-rules/{id} Requires scope `monitor-rules:delete`. # Get a monitor rule Source: https://docs.assistable.ai/api-reference/monitor-rules/get-a-monitor-rule /direct/openapi.json get /v3/monitor-rules/{id} Requires scope `monitor-rules:read`. # List monitor rules Source: https://docs.assistable.ai/api-reference/monitor-rules/list-monitor-rules /direct/openapi.json get /v3/monitor-rules Requires scope `monitor-rules:list`. # Update a monitor rule Source: https://docs.assistable.ai/api-reference/monitor-rules/update-a-monitor-rule /direct/openapi.json patch /v3/monitor-rules/{id} Requires scope `monitor-rules:update`. # Add phone numbers to a pool Source: https://docs.assistable.ai/api-reference/number-pools/add-phone-numbers-to-a-pool /direct/openapi.json post /v3/number-pools/{id}/add-numbers Requires scope `numbers:update`. # Create a number pool Source: https://docs.assistable.ai/api-reference/number-pools/create-a-number-pool /direct/openapi.json post /v3/number-pools Requires scope `numbers:create`. # Delete a number pool Source: https://docs.assistable.ai/api-reference/number-pools/delete-a-number-pool /direct/openapi.json delete /v3/number-pools/{id} Requires scope `numbers:delete`. # Get a number pool Source: https://docs.assistable.ai/api-reference/number-pools/get-a-number-pool /direct/openapi.json get /v3/number-pools/{id} Requires scope `numbers:read`. # List number pools Source: https://docs.assistable.ai/api-reference/number-pools/list-number-pools /direct/openapi.json get /v3/number-pools Requires scope `numbers:list`. # Remove phone numbers from a pool Source: https://docs.assistable.ai/api-reference/number-pools/remove-phone-numbers-from-a-pool /direct/openapi.json post /v3/number-pools/{id}/remove-numbers Requires scope `numbers:update`. # Update a number pool Source: https://docs.assistable.ai/api-reference/number-pools/update-a-number-pool /direct/openapi.json patch /v3/number-pools/{id} Requires scope `numbers:update`. # Assign a phone number to an assistant Source: https://docs.assistable.ai/api-reference/phone-numbers/assign-a-phone-number-to-an-assistant /direct/openapi.json post /v3/phone-numbers/{id}/assign Requires scope `numbers:update`. # Get a phone number Source: https://docs.assistable.ai/api-reference/phone-numbers/get-a-phone-number /direct/openapi.json get /v3/phone-numbers/{id} Requires scope `numbers:read`. # List owned phone numbers Source: https://docs.assistable.ai/api-reference/phone-numbers/list-owned-phone-numbers /direct/openapi.json get /v3/phone-numbers Requires scope `numbers:list`. # Update a phone number Source: https://docs.assistable.ai/api-reference/phone-numbers/update-a-phone-number /direct/openapi.json patch /v3/phone-numbers/{id} Requires scope `numbers:update`. # Add a user to a subaccount Source: https://docs.assistable.ai/api-reference/subaccounts/add-a-user-to-a-subaccount /direct/openapi.json post /v3/subaccounts/{id}/users Requires scope `subaccounts:update`. # Create a subaccount — Assistable Direct (name), or provision from a GoHighLevel Location ID (location_id) Source: https://docs.assistable.ai/api-reference/subaccounts/create-a-subaccount-—-assistable-direct-name-or-provision-from-a-gohighlevel-location-id-location_id /direct/openapi.json post /v3/subaccounts Requires scope `subaccounts:create`. # Credit a subaccount or workspace wallet Source: https://docs.assistable.ai/api-reference/subaccounts/credit-a-subaccount-or-workspace-wallet /direct/openapi.json post /v3/subaccounts/{id}/wallet/credit Requires scope `billing:update`. # Debit a subaccount or workspace wallet Source: https://docs.assistable.ai/api-reference/subaccounts/debit-a-subaccount-or-workspace-wallet /direct/openapi.json post /v3/subaccounts/{id}/wallet/debit Requires scope `billing:update`. # Get a subaccount Source: https://docs.assistable.ai/api-reference/subaccounts/get-a-subaccount /direct/openapi.json get /v3/subaccounts/{id} Requires scope `subaccounts:read`. # Get a subaccount's wallet balances Source: https://docs.assistable.ai/api-reference/subaccounts/get-a-subaccounts-wallet-balances /direct/openapi.json get /v3/subaccounts/{id}/wallet Requires scope `billing:read`. # List subaccount users Source: https://docs.assistable.ai/api-reference/subaccounts/list-subaccount-users /direct/openapi.json get /v3/subaccounts/{id}/users Requires scope `subaccounts:read`. # List subaccounts Source: https://docs.assistable.ai/api-reference/subaccounts/list-subaccounts /direct/openapi.json get /v3/subaccounts Requires scope `subaccounts:list`. Returns up to 100 subaccounts per page. When `meta.next_cursor` is non-null, pass it as the `cursor` query parameter on the next request. Continue until `meta.next_cursor` is null. # Remove a user from a subaccount Source: https://docs.assistable.ai/api-reference/subaccounts/remove-a-user-from-a-subaccount /direct/openapi.json delete /v3/subaccounts/{id}/users/{userId} Requires scope `subaccounts:update`. # Update a subaccount user's role Source: https://docs.assistable.ai/api-reference/subaccounts/update-a-subaccount-users-role /direct/openapi.json patch /v3/subaccounts/{id}/users/{userId} Requires scope `subaccounts:update`. # Create a tag Source: https://docs.assistable.ai/api-reference/tags/create-a-tag /direct/openapi.json post /v3/tags Requires scope `tags:create`. # Delete a tag Source: https://docs.assistable.ai/api-reference/tags/delete-a-tag /direct/openapi.json delete /v3/tags/{id} Requires scope `tags:delete`. # Get a tag Source: https://docs.assistable.ai/api-reference/tags/get-a-tag /direct/openapi.json get /v3/tags/{id} Requires scope `tags:read`. # List tags Source: https://docs.assistable.ai/api-reference/tags/list-tags /direct/openapi.json get /v3/tags Requires scope `tags:list`. # Permanently delete a tag Source: https://docs.assistable.ai/api-reference/tags/permanently-delete-a-tag /direct/openapi.json post /v3/tags/{id}/permanent-delete Requires scope `tags:delete`. # Update a tag Source: https://docs.assistable.ai/api-reference/tags/update-a-tag /direct/openapi.json patch /v3/tags/{id} Requires scope `tags:update`. # Assign a tool to an assistant Source: https://docs.assistable.ai/api-reference/tools/assign-a-tool-to-an-assistant /direct/openapi.json post /v3/tools/{id}/assign Requires scope `tools:update`. # Copy a tool into this subaccount Source: https://docs.assistable.ai/api-reference/tools/copy-a-tool-into-this-subaccount /direct/openapi.json post /v3/tools/{id}/copy Requires scope `tools:create`. # Create a tool Source: https://docs.assistable.ai/api-reference/tools/create-a-tool /direct/openapi.json post /v3/tools Requires scope `tools:create`. # Delete (soft) a tool Source: https://docs.assistable.ai/api-reference/tools/delete-soft-a-tool /direct/openapi.json delete /v3/tools/{id} Requires scope `tools:delete`. # Get a tool (with parameters + headers) Source: https://docs.assistable.ai/api-reference/tools/get-a-tool-with-parameters-+-headers /direct/openapi.json get /v3/tools/{id} Requires scope `tools:read`. # List an assistant's tools Source: https://docs.assistable.ai/api-reference/tools/list-an-assistants-tools /direct/openapi.json get /v3/assistants/{id}/tools Requires scope `tools:read`. # List distinct tool categories Source: https://docs.assistable.ai/api-reference/tools/list-distinct-tool-categories /direct/openapi.json get /v3/tools/categories Requires scope `tools:read`. # List tools Source: https://docs.assistable.ai/api-reference/tools/list-tools /direct/openapi.json get /v3/tools Requires scope `tools:list`. # Remove a tool from an assistant Source: https://docs.assistable.ai/api-reference/tools/remove-a-tool-from-an-assistant /direct/openapi.json post /v3/tools/{id}/remove Requires scope `tools:update`. # Update a tool Source: https://docs.assistable.ai/api-reference/tools/update-a-tool /direct/openapi.json patch /v3/tools/{id} Requires scope `tools:update`. # Update Assistant Source: https://docs.assistable.ai/api-reference/update-assistant /api-reference/assistant-api.json put /v2/update-assistant # Distinct voice filter options Source: https://docs.assistable.ai/api-reference/voices/distinct-voice-filter-options /direct/openapi.json get /v3/voices/filter-options Requires scope `voices:read`. # Get a voice Source: https://docs.assistable.ai/api-reference/voices/get-a-voice /direct/openapi.json get /v3/voices/{id} Requires scope `voices:read`. # List voices Source: https://docs.assistable.ai/api-reference/voices/list-voices /direct/openapi.json get /v3/voices Requires scope `voices:list`. # Toggle whether a custom voice can be copied Source: https://docs.assistable.ai/api-reference/voices/toggle-whether-a-custom-voice-can-be-copied /direct/openapi.json patch /v3/voices/{id}/allow-copy Requires scope `voices:update`. # Voice library stats Source: https://docs.assistable.ai/api-reference/voices/voice-library-stats /direct/openapi.json get /v3/voices/stats Requires scope `voices:read`. # AI Replying Tag Source: https://docs.assistable.ai/build/chat-ai/ai-replying-tag Use the ai_replying tag to build fallback workflows and monitor AI response generation. ## How the AI Replying Tag Works Whenever an AI is generating a response, the tag `ai_replying` is automatically added to the contact. This tag is: * **Added** before AI generation begins * **Removed** after the message is successfully sent to the CRM (i.e., a messageId is available) You can see this in real-time in the AI portal during response generation. ## Use Cases ### Fallback Workflows Use the `ai_replying` tag to trigger a workflow with a **wait timeout**. This is helpful for: * **Vendor or platform timeouts** — If the AI takes too long, trigger an alternative action * **Server maintenance** — Provide a fallback response if the AI service is temporarily unavailable * **Decision-making** — Build logic around whether the AI successfully replied ### Example Workflow 1. Trigger: `ai_replying` tag added 2. Wait: 30 seconds 3. Check: Is `ai_replying` still present? 4. If yes → Send fallback message or notify team 5. If no → AI replied successfully, no action needed # AI Chat Widget Source: https://docs.assistable.ai/build/chat-ai/chat-widget Deploy an AI-powered voice widget on your website with Call You / Call Me functionality. ## AI Voice Widget (Beta) The AI Voice Widget enables a **Call You / Call Me** interface on your website. Visitors can either receive a call from your AI assistant or initiate a call to it directly from the browser. ## Installation To install the widget, you'll need to customize a few lines of the embed code: | Line | What to Change | Example | | ---- | ------------------------------ | ---------------- | | 327 | Phone number (pretty format) | `(678) 931-7883` | | 330 | Phone number (raw format) | `+16789317883` | | 416 | GHL Inbound Webhook URL | Your webhook URL | | 523 | Phone number (no country code) | `6789317883` | ### Embedding Steps Copy the provided HTML/CSS/JavaScript code from the widget builder. Replace the placeholder phone numbers with your AI assistant's assigned number. Add your GoHighLevel inbound webhook URL to capture lead data. Paste the code into a custom HTML/code element on your website. This widget works on any website that supports custom HTML embedding — not just GoHighLevel sites. # Global Kill Switch (ai_off) Source: https://docs.assistable.ai/build/chat-ai/kill-switch Instantly disable AI responses for any contact using the ai_off tag. ## Overview The `ai_off` tag is a global kill switch that immediately stops AI from responding to a contact — even if an Active Tag is present. This gives you full control over when AI should and shouldn't engage. ## For Chat AI Add the tag `ai_off` to the contact in GoHighLevel. The AI will stop responding immediately. Send a test message like "Can you help me?" — confirm the AI does not respond. Remove the `ai_off` tag. The AI resumes normal chat behavior. ## For Voice AI You can use the same tag in voice workflows: 1. Create a conditional workflow (IVR AI Switch) 2. Add a condition: **If contact tag does NOT include `ai_off`** → Proceed with AI 3. **If contact tag includes `ai_off`** → Route to human agent or manual transfer ## Automation Tips * Use a GHL workflow to automatically apply `ai_off` when a human agent takes over a conversation * Remove `ai_off` when the human is done and you want AI to resume * Create a custom button or toggle in your CRM to quickly add/remove the tag # Chat AI Overview Source: https://docs.assistable.ai/build/chat-ai/overview Deploy AI chat assistants that respond to SMS and live chat without workflows, API calls, or webhooks. ## How Chat AI Works Assistable's Chat AI responds to contacts automatically using **Active Tags**. No workflows, API calls, or webhooks are needed. When a message comes in and an Active Tag is detected on the contact, the system knows which assistant should respond. ### Active Tag Behavior * **No Active Tag** → AI won't reply, but it still logs the conversation and adds it to the assistant's memory * **Active Tag Present** → System checks which assistant is linked to that tag and generates a response ### Setting Up Active Tags 1. Go to **Active Tags** in the sidebar menu 2. Create a tag with a unique name 3. Link it to an AI Assistant Make your active tags unique so they don't conflict with existing CRM or contact list tags. You can dynamically reassign which assistant is tied to a tag without redoing your automation setup. ## Turning Chat AI On and Off ### Turning AI On Assign an Active Tag to a contact. The easiest way is to enroll contacts into a GHL workflow that applies the tag. You can trigger this automatically (e.g., when a form is submitted). ### Turning AI Off Three methods: 1. **Remove the Active Tag** — No Active Tag = AI is off 2. **Apply the `ai_off` tag** — Global kill switch that overrides Active Tags. [Learn more](/build/chat-ai/kill-switch) 3. **Sleep Mode** — Temporarily pauses AI when a user or workflow sends a message ### Sleep Mode Sleep Mode pauses AI responses for a set number of minutes after an outbound message is sent. This prevents overlap between human and AI replies. Even automated messages (like appointment confirmations) trigger Sleep Mode. Be careful when enabling this alongside automated workflows. # Calculate Distance Source: https://docs.assistable.ai/build/custom-tools/calculate-distance Create a custom tool that calculates the distance between two locations for your AI assistant. ## Overview The **Calculate Distance** custom tool enables your AI assistant to compute the distance between two addresses or locations during a conversation. This is useful for service-area businesses (e.g., delivery, home services, moving companies) that need to determine if a customer is within range or provide distance-based pricing. Calculate Distance custom tool configuration ## Use Cases * **Home service businesses** — Determine if a customer's location is within your service radius * **Delivery services** — Calculate delivery distance for pricing estimates * **Moving companies** — Provide distance-based quotes automatically * **Real estate** — Calculate distance between properties and points of interest ## How It Works The tool accepts two location parameters (origin and destination) and returns the distance between them. Your AI assistant can then use this information to make decisions, provide quotes, or determine service eligibility. In your Assistable dashboard, navigate to your assistant's **Custom Tools** section and click **Create Custom Tool**. Set up the following: * **Unique Name**: `calculate_distance` * **Description**: "Calculate the distance between two addresses" * **Parameters**: `origin` (starting address), `destination` (ending address) Use a service like Buildship or a custom webhook to call a distance API (e.g., Google Maps Distance Matrix API) and return the result. Paste the endpoint URL from your backend service into the custom tool's endpoint field and test the connection. Save the tool and add it to your assistant. Update your prompt to instruct the AI when to use the distance calculation. Combine this tool with [Save Address](/build/custom-tools/save-address) to first collect the user's address, then calculate the distance to your business location. ## Related Pages Learn the fundamentals of custom tools Collect and save user addresses Add web search capabilities Update CRM contact information # Call from SMS Source: https://docs.assistable.ai/build/custom-tools/call-from-sms Create a custom tool that transitions from an SMS conversation to a phone call with full context. ## Overview The **Call from SMS** custom tool enables your AI assistant to initiate a phone call to a user directly from an SMS conversation — while carrying over the full conversation context. This means when the voice assistant calls the user, it already knows what was discussed via text. Call from SMS custom tool configuration ## Why Use This? Some conversations are better handled over the phone — complex scheduling, sensitive information, or when a user explicitly requests a call. This tool bridges the gap between chat and voice seamlessly. **Key benefits:** * **Context preservation** — The voice AI knows what was discussed in SMS * **Seamless transition** — No need for the user to repeat themselves * **User-initiated** — The AI calls when the user is ready ## How It Works When the AI determines a phone call would be more effective (or the user requests one), it triggers this tool. The tool uses the Assistable API to initiate an outbound call to the contact, passing along the conversation context so the voice assistant can pick up where the SMS left off. Navigate to **Custom Tools** in your assistant settings and create a new tool named `call_user_from_sms`. Set the description to: *"Call this tool when the user wants to switch from SMS to a phone call. The voice assistant will have full context of the SMS conversation."* Use the [Assistable API](/api-reference) to trigger an outbound call. The endpoint should pass the `contact_id` and conversation summary to the voice assistant. Add instructions telling the AI when it's appropriate to offer a phone call (e.g., complex topics, user frustration, or explicit requests). This tool requires a [Voice AI setup](/build/voice-ai/overview) with an active phone number configured for outbound calling. ## Related Pages The reverse — send texts during voice calls Send conversation summaries to clients Configure voice AI assistants Learn the fundamentals of custom tools # Managing Tools Source: https://docs.assistable.ai/build/custom-tools/managing-tools Copy, search, and organize custom tools across accounts. ## Tool Management in Assistant Builder ### Adding Tools 1. Open the Assistant Builder and go to **Tools** 2. Click **Add Tool** to browse available tools 3. Select or search for the tool you want to add ### Copying Tools by ID Custom tools can be copied and shared using their Tool ID: 1. Get the **Tool ID** from the source account 2. In the destination account, enter the ID in the "Copy Tool by ID" field 3. Click **Copy Tool by ID** to import it Authentication credentials (API keys) are NOT transferred for security reasons. You'll need to re-enter them after copying. ### Searching and Filtering Use the search bar and filtering options to quickly find tools when managing a large collection. ### Deleting Tools The delete option has been moved to prevent accidental deletions. Look for it in the tool's options menu rather than the main interface. # Multi-Calendar Booking Source: https://docs.assistable.ai/build/custom-tools/multi-calendar-booking Set up multi-calendar booking with custom tools to manage appointments across multiple calendars. ## Overview Multi-calendar booking allows your AI assistant to manage appointments across **multiple GoHighLevel calendars** — for example, different service types (mortgage vs. refinance), different locations, or different team members. This guide walks through setting up the custom tools, Buildship workflows, and AI configuration needed. Multi-calendar booking flow diagram ## How It Works For each calendar, you create **two custom tools**: 1. **Get Available Times** — Fetches open time slots from a specific calendar 2. **Book Appointment** — Books an appointment on that calendar The AI determines which service the user needs, calls the appropriate tools, and completes the booking — all within a single conversation. ## Prerequisites * **GoHighLevel Account** with multiple calendars set up * **Buildship Account** to create and host API endpoints * **Assistable AI Assistant** to add custom tools and configure prompts ## Step-by-Step Setup Create separate calendars for each service type. For example: * **Mortgage Calendar** for mortgage-related appointments * **Refinance Calendar** for refinance-related appointments Note each calendar's unique ID — you'll need it for the API calls. Create a new Buildship workflow: * **Name**: `get_times_mortgage` (or your service name) * **Method**: GET request to GoHighLevel's free time slots endpoint * **Query Parameters**: `calendarId`, `startTime`, `endTime` * **Headers**: `Authorization: Bearer YOUR_API_KEY` Deploy and copy the endpoint URL. Get available times Buildship workflow Create another Buildship workflow: * **Name**: `book_appointment_mortgage` * **Method**: POST request to GoHighLevel's booking endpoint * **Request Body**: `calendarId`, `contactId`, `locationId`, `startTime` (ISO 8601) * **Headers**: `Authorization`, `Content-Type: application/json` Deploy and copy the endpoint URL. Book appointment Buildship workflow In Assistable, create custom tools matching your Buildship workflows: **Get Available Times:** * Name: `get_times_mortgage` * Description: "Fetch available times for the mortgage calendar" * Endpoint: Your Buildship URL * Parameters: `name`, `email` **Book Appointment:** * Name: `book_appointment_mortgage` * Description: "Book an appointment using the selected time from get\_times\_mortgage" * Endpoint: Your Buildship URL * Parameters: `time` Create the same pair of tools for every additional calendar (e.g., `get_times_refinance`, `book_appointment_refinance`). Define the workflow in your prompt: 1. Determine the service type (mortgage or refinance) 2. Ask qualifying questions 3. Use the appropriate `get_times` tool to fetch availability 4. Present options and book via the matching `book_appointment` tool Simulate user interactions for each service type. Verify: * Correct calendar is queried * Appointments appear in GoHighLevel under the right calendar * Contact details are accurate ## Tips Keep tool names uniform across Buildship and Assistable (e.g., `get_times_mortgage` in both places). Protect API keys using Buildship's environment variables — never hardcode them. Pass calendar IDs as dynamic parameters so you can add new calendars without creating entirely new tools. ## Related Pages Learn the fundamentals of custom tools Troubleshoot booking issues Extract user data automatically Build smarter AI flows # Custom Tools Overview Source: https://docs.assistable.ai/build/custom-tools/overview Extend your AI assistant with powerful API-driven custom tools. ## What is a Custom Tool? Custom tools are powerful extensions that enable voice and chat AI to perform tasks across the internet. They enable custom functionality, data retrieval, data extraction, and workflow automation while understanding and responding contextually. ### How Does a Custom Tool Work? A custom tool operates as an **LLM function call wrapped in an API call**. It specifies AI functionality through a description and parameters, while the endpoint URL facilitates a POST call with contextual awareness of the endpoint's return data. ## Use Cases The applications are as broad as your creativity: * **Update contact information** — AI collects details and sends them to a webhook to update CRM records * **Book appointments** across multiple calendars * **Search the web** for real-time information * **Calculate distances** between locations * **Send emails or SMS** during conversations * **Scrape websites** for relevant data * **Advanced workflows** — Multi-stage tool calls (e.g., generate Stripe checkout links, send via SMS) ## Understanding the Inputs ### Name (raw JSON format) The unique name of the tool, triggered when the AI determines conditions match. Use plain raw text reflecting the function: * `update_contact` — For updating contact information * `get_delivery_date` — For retrieving delivery dates ### Description (conversational text) Guides the AI on the tool's purpose, how to use it, and when to trigger it. Example: > "Retrieve the delivery date for a customer's order. Use this tool when a customer asks 'Where is my package?'" ### Endpoint URL Where the AI sends a POST request with data and expects a response. This is the specific API or webhook endpoint. ### Authorization & Key Enable authentication using Bearer Token format for endpoints that require API keys. ### Parameters (Key/Value Pairs) Define the data being requested. Keys should follow JSON conventions (lowercase, underscores, no special characters). Values describe the expected data and format. Example: ```json theme={null} {"name": "johnny"} ``` # Save Address Source: https://docs.assistable.ai/build/custom-tools/save-address Create a custom tool to collect and save a user's complete address to their contact profile. ## Overview The **Save Address** custom tool enables your AI assistant to collect a user's full address (street, city, state, zip code) during a conversation and save it directly to the contact profile in GoHighLevel. This is particularly useful for service businesses that need addresses for appointments, inspections, or deliveries. Since Version 2.1, Assistable includes a **pre-built** tool with this functionality. This guide is still useful for learning how to build custom tools from scratch. Save Address custom tool overview ## Prerequisites * **AI Assistant Dashboard** — Access to custom tool creation * **GoHighLevel CRM** — Access to automation workflows and contact profile fields * **Endpoint URL** — Generated from an inbound webhook ## Step-by-Step Setup In your assistant dashboard: 1. Go to **Assistants** → select your assistant 2. Under **Custom Tools**, click **Create a Custom Tool** 3. Configure: * **Unique Name**: `save_address` * **Description**: "Use this tool to collect and save the user's complete address including street, city, state, and zip code." * **Parameters**: `street`, `city`, `state`, `zip_code` * **Example Data**: "54 State Street, Albany, New York, 12207" 1. In GoHighLevel, go to **Automations** → create a new workflow titled "Save Address Webhook" 2. Set **Inbound Webhook** as the trigger 3. Copy the generated Webhook URL 4. Return to your custom tool setup and paste the URL in the endpoint field 5. Test the connection (look for a green checkmark) In your assistant's **Prompts** section, add instructions like: *"Ask the user for their full address, including the zip code. Once collected, call the save\_address function."* Back in the GoHighLevel automation: 1. Click **Fetch Sample Request** to pull sample data 2. Add a **Find Contact** action using `contact_id` from the webhook 3. Add **Update Contact Field** actions mapping each field: * Street Address → `Inbound Webhook > Arguments > street` * City → `Inbound Webhook > Arguments > city` * State → `Inbound Webhook > Arguments > state` * Postal Code → `Inbound Webhook > Arguments > zip_code` 4. Save and publish the workflow 1. Run a test conversation with your AI assistant 2. Provide an address when prompted 3. Check the contact's **General Info** section in GoHighLevel 4. Verify all address fields are correctly populated ## FAQs Ensure each address component (street, city, state, zip) is mapped to the correct field in the Update Contact Field action. Yes — modify the tool parameters and field mappings to capture email, phone, or any other contact information. Verify the custom tool is added to the assistant and that your prompt explicitly instructs the AI to call the tool after collecting the address. ## Related Pages Calculate distance from the saved address Update any contact field in GoHighLevel Automatically fill custom fields Extract user information automatically # Scrape Website Source: https://docs.assistable.ai/build/custom-tools/scrape-website Create a custom tool that scrapes website content and returns it for your AI assistant to understand. ## Overview The **Scrape Website** custom tool allows your AI assistant to fetch and read the contents of any website URL during a conversation. The scraped content is returned to the AI, which can then analyze, summarize, or answer questions about it. Scrape Website custom tool configuration ## Use Cases * **Lead research** — AI scrapes a prospect's website to personalize the conversation * **Competitor analysis** — Fetch and summarize competitor pages on demand * **Content verification** — Check if specific information exists on a webpage * **Support** — Pull documentation or help articles in real time ## How It Works The tool accepts a URL parameter, makes an HTTP request to fetch the page content, parses the HTML into readable text, and returns it to the AI assistant. The AI can then use this content as context for its responses. In your assistant settings, create a new custom tool: * **Name**: `scrape_website` * **Description**: "Scrape and return the text content of a given website URL" * **Parameters**: `url` (the website to scrape) Use Buildship or a custom webhook to: 1. Receive the URL parameter 2. Fetch the webpage content 3. Parse HTML to extract readable text 4. Return the text content to the AI If your scraping endpoint requires authentication, add the authorization header in the tool configuration. Save the tool, add it to your assistant, and test by asking the AI to look up information from a specific URL. Be mindful of rate limits and website terms of service when scraping. Some sites block automated requests. ## Related Pages Capture visual screenshots instead Search the web with your AI Learn custom tool fundamentals Optimize your AI's knowledge # Screenshot Website Source: https://docs.assistable.ai/build/custom-tools/screenshot-website Create a custom tool that captures a screenshot of any website for your AI assistant. ## Overview The **Screenshot Website** custom tool allows your AI assistant to capture a visual screenshot of any webpage. This is useful for visual verification, design reviews, or providing users with a preview of a website. Screenshot Website custom tool configuration ## Use Cases * **Website previews** — Show users what a page looks like before visiting * **Design verification** — Confirm landing pages render correctly * **Documentation** — Capture visual evidence of web content * **QA testing** — Verify deployment changes visually ## Setup Create a new custom tool in your assistant: * **Name**: `screenshot_website` * **Description**: "Take a screenshot of the specified website URL" * **Parameters**: `url` (the website to screenshot) Use a screenshot API service (e.g., ScreenshotAPI, Puppeteer via Buildship) that accepts a URL and returns an image. Paste the service endpoint into the tool configuration, save, and test by asking your AI to screenshot a website. Pair this with the [Scrape Website](/build/custom-tools/scrape-website) tool to get both visual and text content from a page. ## Related Pages Extract text content from websites Add web search to your AI Custom tool fundamentals # Search the Web Source: https://docs.assistable.ai/build/custom-tools/search-web Create a custom tool that enables your AI assistant to search the web in real time. ## Overview The **Search the Web** custom tool gives your AI assistant the ability to perform live web searches during a conversation. The tool calls the Bing search engine and returns results that the AI can use to answer questions with up-to-date information. Search the Web custom tool configuration ## Use Cases * **Real-time information** — Answer questions about current events, pricing, or availability * **Research** — Look up businesses, products, or services during a conversation * **Fact-checking** — Verify claims or find supporting information * **Competitive intelligence** — Research competitors on behalf of users ## Setup In your assistant settings, create a new tool: * **Name**: `search_the_web` * **Description**: "Search the web for real-time information using the Bing search engine" * **Parameters**: `query` (the search terms) Set up a Buildship workflow or webhook that: 1. Receives the search query 2. Calls the Bing Search API (or similar search service) 3. Returns formatted search results to the AI Connect the endpoint, save, and update your prompt to instruct the AI when to use web search (e.g., for questions outside its knowledge base). To call the tool, use `search_the_web` — the response will contain results from the Bing search engine. Combine with your [Knowledge Base](/troubleshooting/knowledge-base-optimization) so the AI tries internal knowledge first and only searches the web when needed. ## Related Pages Scrape specific pages for detailed content Capture visual screenshots Custom tool fundamentals Build a better knowledge base # Send Conversation Summary Source: https://docs.assistable.ai/build/custom-tools/send-summary Create a custom tool that sends conversation summaries to your clients via email or SMS. ## Overview The **Send Conversation Summary** tool enables your AI assistant to capture a summary of the conversation and deliver it to your clients (or your team) via email, SMS, or any notification channel. This keeps stakeholders informed about what was discussed without manually reviewing transcripts. Conversation Summary custom tool ## How It Works Go to **Settings > Custom Fields** in your GHL sub-account and create a new field called `conversation_summary` (type: Multi-line Text). In your AI assistant, set up a custom **Extraction** tool that automatically populates the `conversation_summary` custom field with an AI-generated summary of the conversation. Create a workflow triggered by a specific event (e.g., **Appointment Booked**): 1. Add an **SMS** or **Email** action 2. Include the custom field variable: `{{contact.conversation_summary}}` 3. The client receives a summary of what was discussed ## Example Workflow After a booking call, your client receives: > *"Summary: John called about a roof inspection at 54 State St. He prefers morning appointments and has a budget of \$500. Appointment booked for Tuesday 10am."* This pairs well with the [Transcript Workflows](/how-to-guides/transcript-workflows) guide for sending full conversation transcripts. ## Related Pages Send full conversation transcripts Extract data automatically Auto-fill custom fields Custom tool fundamentals # Submit Support Ticket Source: https://docs.assistable.ai/build/custom-tools/submit-ticket Create a custom tool that submits support tickets on behalf of users during AI conversations. ## Overview The **Submit Support Ticket** custom tool allows your AI assistant to create and submit support tickets on behalf of users during a conversation. When a user reports an issue that can't be resolved immediately, the AI collects the details and submits a ticket to your support system. Submit Support Ticket custom tool ## Use Cases * **Customer support** — Escalate issues the AI can't resolve * **Bug reports** — Collect technical details and submit automatically * **Feature requests** — Capture and route user feedback * **Service requests** — Create work orders or service tickets ## Setup In your assistant settings, create a new tool: * **Name**: `submit_support_ticket` * **Description**: "Submit a support ticket on behalf of the user with their issue details" * **Parameters**: `subject`, `description`, `priority` (optional), `category` (optional) Create an inbound webhook in GoHighLevel (or your ticketing system) that: 1. Receives the ticket data 2. Creates a support ticket or task 3. Notifies the appropriate team Instruct the AI to: * Try to resolve the issue first * If unable, collect all relevant details * Confirm the ticket details with the user before submitting * Provide a confirmation after submission Simulate a support scenario and verify the ticket appears in your system with all details intact. Add the user's contact information automatically using [variables](/build/variables-reference) like `{{contact.email}}` and `{{contact.phone}}`. ## Related Pages Update contact information in CRM Send conversation summaries Custom tool fundamentals # Update Contact in GoHighLevel Source: https://docs.assistable.ai/build/custom-tools/update-contact Create a custom tool to update contact information in GoHighLevel from AI conversations. ## Overview The **Update Contact** custom tool enables your AI assistant to update contact information directly in GoHighLevel during a conversation. The AI collects information naturally and pushes it to the CRM — no manual data entry required. Since Version 2.1, Assistable includes a **pre-built** tool for this. This guide is helpful for learning how to build custom tools from scratch. Update Contact custom tool overview ## How It Works The tool uses a GoHighLevel inbound webhook workflow: 1. **AI collects data** during conversation (name, email, etc.) 2. **Tool fires** with the collected data as parameters 3. **Webhook triggers** a GHL automation workflow 4. **Workflow finds contact** by contact ID and updates the specified fields ## Setup * **Name**: `update_contact_info` * **Description**: "Update the user's contact information in the CRM" * **Parameters**: Define fields you want to update (e.g., `email`, `name`, `phone`, `company`) 1. Go to **Automations** → Create new workflow 2. Set trigger to **Inbound Webhook** 3. Copy the webhook URL to your custom tool's endpoint field Inbound webhook trigger Add a **Find Contact** action: * Search by **Contact ID** using the `contact_id` from the webhook payload Find contact by ID Add **Update Contact** actions mapping each field from the webhook's arguments: Update contact fields from webhook args Publish the workflow, then test by having the AI collect and update contact information during a conversation. ## Related Pages Save user addresses to contact profiles Automatically extract user information Auto-fill custom fields Custom tool fundamentals # Setting Up Your API Key Source: https://docs.assistable.ai/build/flow-builder/api-key Configure your LLM API key for Flow Builder using OpenAI, Anthropic, or OpenRouter. ## Overview Flow Builder uses a **Bring Your Own Key (BYOK)** model. You provide your own LLM API key, and the platform routes all AI calls through your account. This gives you control over costs, rate limits, and model access. An API key is **required** before you can test or deploy any flow. Without one, Conversation and Extraction nodes have no LLM to call. ## Supported Providers | Provider | Key Format | Models | | -------------- | ------------ | ----------------------------------- | | **OpenAI** | `sk-...` | GPT-4o, GPT-4o-mini, GPT-4, etc. | | **Anthropic** | `sk-ant-...` | Claude Sonnet, Claude Haiku, etc. | | **OpenRouter** | `sk-or-...` | 100+ models from multiple providers | ## Adding Your Key Click the **Settings** icon (gear) in the top toolbar. Choose OpenAI, Anthropic, or OpenRouter from the dropdown. Enter your API key and click **Save**. Select the default model for the flow. Individual nodes can override this in their advanced settings. ## Model Recommendations * **Voice flows** (latency matters): `gpt-4o-mini` or `claude-haiku` * **Complex reasoning**: `gpt-4o` or `claude-sonnet` * **Multi-provider access**: Use **OpenRouter** for a single key across all providers ## Troubleshooting | Issue | Solution | | ----------------------- | ------------------------------------------------ | | "No API key configured" | Open Settings and verify your key is saved | | 401 Unauthorized | Check that your key is valid and hasn't expired | | Model not available | Ensure your API plan includes the selected model | | Rate limit errors | Check your provider's usage dashboard | Your API key is never shared with other users or flows. Each flow stores its own key independently. ## Related Pages Test your flow with your key How models are resolved Deploy to voice # Conversation Node Source: https://docs.assistable.ai/build/flow-builder/conversation-node The core building block of Flow Builder where your AI engages with users in natural conversation. ## Overview The Conversation node is the heart of every flow. It's the **only node type that directly communicates with the user** — generating responses, handling dialogue, and deciding when to transition to the next step. Every flow must have at least one Conversation node (the start node), and most flows have several. ## Instruction Modes ### Prompt Mode (Default) The node's instruction becomes the system prompt for the LLM. The AI generates conversational responses based on this prompt and the conversation history. This is the mode you'll use 95% of the time. ``` You are a scheduling assistant for Acme Dental. Ask the caller for their preferred date and time. Only offer weekday slots between 9 AM and 5 PM. Confirm the details before proceeding. ``` The prompt supports `{{variable}}` substitution for dynamic personalization: ``` You are speaking with {{caller_name}}. Their account number is {{account_id}}. Greet them by name and ask how you can help. ``` ### Static Mode The instruction text is sent directly to the user **verbatim** — no LLM call is made. Use this for fixed messages like greetings or disclaimers. If the conversation revisits a static node (e.g., via a loop), it automatically switches to prompt mode on subsequent visits. Static mode only applies on the first visit. ## Transitions Transitions are the most powerful feature of the Conversation node. Each transition is a condition that, when met, moves the conversation to a connected node. ### How Transitions Work Under the hood, each transition condition is registered as a **tool/function call** with the LLM. When the AI determines a condition is met, it fires the corresponding tool call instead of generating a regular response. The engine then follows the edge to the destination node, which generates the actual response. This means **transitions and responses happen in a single LLM call** — the source node decides to transition, and the destination node speaks. This is what keeps Flow Builder fast for voice. ### Adding Transitions Click the **+ Add Transition** button on a Conversation node. Each transition has: * **Condition** — A natural language description (e.g., "The user confirms their appointment") * **Edge handle** — A green dot appears on the right side of the node. Drag from it to the destination node. ### Must Respond First By default, a Conversation node **skips transition evaluation on its first visit**. The AI responds first, then evaluates transitions on subsequent messages. This prevents the AI from immediately transitioning away before the user hears the node's response. ## AI-Powered Features ### AI Suggest Click the **sparkle icon** to have AI analyze your prompt and automatically suggest likely transition conditions. For example, if your prompt asks about appointment booking, AI Suggest might generate transitions like "User provides a date and time" and "User wants to cancel instead." ### Improve Prompt Click the **magic wand icon** to have AI rewrite your prompt into an optimized, task-based framework. See [Node Builder AI](/build/flow-builder/node-builder-ai) for details. ## Global Nodes Conversation nodes can be marked as **global**, making them accessible from any point in the flow. This is useful for handling universal intents like "I want to speak to a human" or "Cancel my appointment" regardless of where the user is in the conversation. ## Related Pages Route conversations based on conditions Dynamic data and substitution Test your flow in the built-in panel AI-assisted node generation # Embedding the Chat Widget Source: https://docs.assistable.ai/build/flow-builder/embedding-widget Deploy your flow as an embeddable chat widget on any website. ## Overview Flow Builder can generate an embeddable chat widget that you drop into any website. The widget runs your flow as a chat assistant, giving visitors a conversational interface without leaving your site. ## Setup Navigate to your flow in Flow Builder. Click the **Deploy** or **Widget** button in the toolbar. Configure colors, position, and welcome message. Copy the generated embed code. Add the script just before the closing `` tag: ```html theme={null} ``` ## Customization Options | Attribute | Description | Default | | ---------------------- | -------------------------------- | -------------- | | `data-flow-id` | Your flow's unique ID (required) | — | | `data-position` | `bottom-right` or `bottom-left` | `bottom-right` | | `data-primary-color` | Hex color for header and buttons | `#4F46E5` | | `data-welcome-message` | Initial message when opened | — | | `data-button-text` | Launcher button text | `Chat` | ## Technical Details * **Shadow DOM** — Widget styles are completely isolated from your site's CSS * **localStorage** — Conversation persists across page navigations and refreshes * **SPA compatible** — Handles React, Vue, Next.js navigation automatically * **Lightweight** — Loaded asynchronously, no impact on Core Web Vitals * **CSP** — Add `flow.assistable.ai` to `script-src` and `connect-src` if using strict Content Security Policy ## Related Pages Test your flow before embedding Deploy to voice instead Required before deployment # Extraction & Variable Nodes Source: https://docs.assistable.ai/build/flow-builder/extraction-variable-nodes Extract structured data from conversations and set variable values in your flows. ## Overview Flow Builder has two nodes for working with data: the **Extraction node** uses an LLM to pull structured information from the conversation, and the **Variable node** sets values directly without AI involvement. ## Extraction Node The Extraction node analyzes conversation history and extracts specific data into named variables. ### Configuring Extractions Each extraction has three fields: | Field | Description | Example | | ------------- | ---------------------------------- | ---------------------------- | | `varName` | Variable to store the value | `caller_email` | | `varType` | Expected data type | `string` | | `description` | What to extract (natural language) | "The caller's email address" | ### Supported Types | Type | Example Values | | --------- | ----------------------------------- | | `string` | `john@example.com` | | `number` | `42` | | `boolean` | `true` | | `array` | `["Mon", "Wed", "Fri"]` | | `object` | `{"city": "Austin", "state": "TX"}` | ### Sentinel Sanitization The extraction engine automatically converts ambiguous values (``, `N/A`, `null`, `none`, `not provided`) to empty strings. This ensures `is_empty` checks in [Logic nodes](/build/flow-builder/logic-node) work correctly. Connect Extraction nodes via the **async handle** when you don't need the extracted data immediately — this keeps the conversation flowing while extraction runs in the background. ## Variable Node The Variable node sets values directly — no LLM call, instant execution. ### Literal Values ``` varName: lead_status value: qualified ``` ### Dynamic Values with Substitution ``` varName: full_address value: {{street}}, {{city}}, {{state}} {{zip}} ``` ## Common Pattern Chain these nodes together: 1. **Conversation node** — Ask the user for information 2. **Extraction node** — Extract `first_name`, `last_name`, `email` 3. **Variable node** — Compose `full_name` as `{{first_name}} {{last_name}}` 4. **Logic node** — Check if required fields are present 5. **Request node** — POST to your CRM ## Related Pages Variable system and substitution syntax Branch based on extracted values Send extracted data to APIs How-to guide for data extraction # Getting Started with Flow Builder Source: https://docs.assistable.ai/build/flow-builder/getting-started Build complex conversational AI flows with a visual drag-and-drop builder. ## What is Flow Builder? Flow Builder is a visual drag-and-drop interface for creating complex conversational AI agents. Instead of relying on a single prompt, you can design multi-step conversation flows with branching logic, API calls, variable extraction, and more. ## Key Concepts * **Nodes** — Individual steps in your conversation flow * **Connections** — Links between nodes that define the conversation path * **Variables** — Dynamic data that persists across the flow * **Conditions** — Logic that determines which path to take ## Getting Started Navigate to **Flow Builder** and click **Create New Flow**. Give it a descriptive name. Start with a **Conversation Node** — this is the core building block where your AI engages with the user. Connect nodes together to create your desired conversation path. Use Logic Nodes for branching, Tool Nodes for API calls, and Extraction Nodes to capture data. Use the built-in testing interface to simulate conversations and verify your flow works correctly. ## Node Types The core node where AI engages with users. Conditional branching based on variables or conditions. Execute custom tools and API calls. Extract and store data from conversations. Make HTTP API calls to external services. Use AI to generate node configurations. # Logic Node Source: https://docs.assistable.ai/build/flow-builder/logic-node Route conversations based on variable values using conditional branching — no LLM call required. ## Overview The Logic node routes conversations based on **variable values**. It evaluates conditions against your flow's variables and sends the conversation down different paths — no LLM call required. Think of it as an `if/else-if/else` block for your flow. ## How Branches Work Each Logic node has one or more **branches**. A branch contains one or more conditions, and each condition checks a variable against a value using an operator. Branches are evaluated **in order, top to bottom**. The first branch whose conditions are all satisfied wins. If no branch matches, the **default path** is taken. ## Branch Logic: AND vs OR | Mode | Behavior | Example | | ------- | --------------------------- | -------------------------------------- | | **AND** | All conditions must be true | Language is English AND state is Texas | | **OR** | Any condition can be true | Status is "VIP" OR spend > 10000 | ## Operators | Operator | Description | Example | | -------------- | ---------------------------- | --------------------------------- | | `equals` | Exact match (case-sensitive) | `{{language}}` equals English | | `not_equals` | Does not match | `{{status}}` not\_equals blocked | | `contains` | Variable contains substring | `{{interests}}` contains dental | | `not_contains` | Does not contain substring | `{{email}}` not\_contains spam | | `not_empty` | Has a value | `{{phone_number}}` not\_empty | | `is_empty` | Empty, null, or unset | `{{email}}` is\_empty | | `greater_than` | Numeric: variable > value | `{{age}}` greater\_than 18 | | `less_than` | Numeric: variable \< value | `{{budget}}` less\_than 500 | | `starts_with` | Begins with string | `{{phone}}` starts\_with +1512 | | `ends_with` | Ends with string | `{{email}}` ends\_with @gmail.com | ## Default Path If you don't connect a default path and no branches match, the engine has nowhere to go and the flow stalls. **Always wire up the default output.** ## Real-World Examples ### Lead Qualification * **Branch 1 (AND)**: budget > 5000 AND company\_size > 10 → "Qualified Lead" conversation * **Branch 2**: budget > 1000 → "Warm Lead" conversation * **Default**: "Nurture" conversation ### Language Routing * **Branch 1**: preferred\_language equals Spanish → Spanish flow * **Branch 2**: preferred\_language equals French → French flow * **Default**: English flow ### Data Completeness Check * **Branch 1 (AND)**: name not\_empty AND email not\_empty AND phone not\_empty → Proceed to API call * **Default**: Loop back to conversation node for missing info ## Related Pages The core dialogue node Dynamic data in your flows Extract data from conversations Comprehensive usage guide # Node Builder (AI Generate) Source: https://docs.assistable.ai/build/flow-builder/node-builder-ai Use AI to generate node configurations, improve prompts, and build flows faster. ## Overview Flow Builder includes AI-powered node generation to help you build faster. Describe what you want in plain language and let the AI generate the configuration — or improve existing prompts with a single click. ## AI Generate (Sparkle Button) On any [Conversation node](/build/flow-builder/conversation-node), click the **sparkle icon** to open the AI Generate panel. Describe the node's purpose: ``` Ask the caller for their appointment date and time preference. Only allow weekday slots between 9am and 5pm. If they ask for a weekend, politely explain that's not available. ``` The AI generates: * A structured **system prompt** optimized for the node * Suggested **transition conditions** based on likely outcomes * Appropriate **node settings** Review and adjust before saving. ## Improve Prompt (Magic Wand) Already have a prompt? Click the **magic wand icon** to rewrite it into a structured, task-based format. ### Before ``` You're a dental receptionist. Help people book appointments. Be nice and professional. Ask for their info. ``` ### After ``` You are a scheduling assistant for Acme Dental. Your task: 1. Greet the caller professionally. 2. Ask for their full name. 3. Ask for their preferred appointment date and time. 4. Only offer weekday slots between 9:00 AM and 5:00 PM. 5. Confirm the appointment details before proceeding. Constraints: - Do not schedule same-day appointments. - If the caller requests a weekend, explain only weekday slots are available. - Keep responses concise and professional. ``` The improved version gives the LLM clearer direction for more consistent behavior. ## Revert Every AI generation is **reversible**. A **Revert** button appears after any AI modification — click it to restore the previous version instantly. No risk of losing your work. ## Related Pages The core dialogue node Test AI-generated nodes Comprehensive usage guide # Request Node (API Calls) Source: https://docs.assistable.ai/build/flow-builder/request-node Make HTTP API calls from within your flow with full control over method, headers, body, and response handling. ## Overview The Request node lets you make HTTP API calls from your flow — send data to external systems, retrieve information, or trigger webhooks. Unlike the [Tool/Function node](/build/flow-builder/tool-function-nodes), it gives you full control over every aspect of the HTTP request. ## Configuration | Field | Description | | --------------------- | --------------------------------------------------- | | **Method** | GET, POST, PUT, PATCH, or DELETE | | **URL** | Endpoint URL (supports `{{variable}}` substitution) | | **Content Type** | Content-Type header value | | **Authorization** | Authorization header (e.g., `Bearer {{api_token}}`) | | **Headers** | Additional headers as key-value pairs | | **Query Parameters** | URL query parameters | | **Body Mode** | `key-value` or `raw` (JSON/text) | | **Response Variable** | Variable name to store the response | | **Await** | Whether to wait for the response | ## Variable Interpolation Every text field supports `{{variable}}` substitution — URLs, headers, authorization, body, everything. **URL example**: `https://api.example.com/customers/{{customer_id}}/appointments` **Body example**: ```json theme={null} { "name": "{{caller_name}}", "email": "{{caller_email}}", "appointment_date": "{{selected_date}}" } ``` ## Response Handling When you set a Response Variable (e.g., `booking_result`), three variables are created: | Variable | Contains | | --------------------------- | ----------------------------------- | | `{{booking_result}}` | Response body (parsed JSON or text) | | `{{booking_result_status}}` | HTTP status code (200, 404, etc.) | | `{{booking_result_error}}` | Error message if request failed | Use a [Logic node](/build/flow-builder/logic-node) after the Request node to branch based on status code or errors. ## Sync vs Async * **Await enabled** — Flow pauses until response arrives. Use when downstream nodes need the data. * **Await disabled** — Flow continues immediately. Use for fire-and-forget operations. Request nodes have a **10-second timeout**. Design your flows to handle timeouts with a Logic node checking the error variable. ## Related Pages Pre-configured API integrations Variable substitution reference Branch on API responses How the engine processes requests # Engine & Streaming Source: https://docs.assistable.ai/build/flow-builder/streaming Understand how Flow Builder's engine processes messages, chains nodes, and streams responses. ## Overview The Flow Builder engine is a **single-loop state machine** that processes one user message at a time. Understanding it helps you build faster, more efficient flows — especially for voice where latency matters. ## The Processing Loop When a user sends a message: 1. **Receive message** — Input is added to conversation history 2. **Process current node** — Engine executes the active node 3. **Chain through silent nodes** — Variable, Logic, Extraction, Function, Request nodes execute automatically in sequence 4. **Stop at Conversation or End** — Loop stops when it reaches a response-generating node Only Conversation nodes produce user-facing responses. All other nodes execute silently. The engine can chain through multiple nodes in a single turn, transparently to the user. ## Node Processing Order | Node Type | What Happens | Blocks? | | ----------------- | ---------------------------------- | -------------------- | | **Conversation** | LLM call with prompt + history | Yes — waits for LLM | | **Tool/Function** | Executes HTTP tool call | Yes — waits for API | | **Extraction** | LLM extracts structured data | Yes — waits for LLM | | **Variable** | Sets values synchronously | No — instant | | **Logic** | Evaluates conditions, picks path | No — instant | | **Request** | Makes HTTP request | Yes (if await: true) | | **End** | Fires webhook, returns end message | No | ## Streaming (SSE) Flow Builder uses **Server-Sent Events** to stream responses in real-time — critical for voice where TTS starts speaking as soon as the first tokens arrive. ### SSE Event Types | Event | Description | | ------------ | ---------------------------------------------------- | | `token` | Individual LLM token chunks | | `filler` | Speak-during-execution text from Tool/Function nodes | | `clear` | Discard partial response — a transition is happening | | `tool_calls` | Tool/function call detected | | `done` | Turn complete with final state | | `error` | Error during processing | The **`clear` event** is key for voice: when the LLM starts responding but then transitions, `clear` tells TTS to stop the partial response and prepare for the new node's output. ## Safety Limits | Limit | Value | Purpose | | ------------------------ | ----------- | -------------------------- | | Max transitions per turn | 10 | Prevents infinite loops | | Max tool call rounds | 5 | Limits recursive execution | | Conversation history cap | 40 messages | Controls context window | | Request timeout | 10 seconds | Prevents hung API calls | Hitting the 10-transition limit means there's likely a loop — check for Logic nodes that cycle without a Conversation node in between. ## LLM Resolution Order The engine determines which model to use by checking (in order): 1. **Node override** — Model set on the specific node 2. **Flow default** — Model set at the flow level 3. **Fallback** — `gpt-4o-mini` Supported providers: OpenAI, Anthropic, and OpenRouter. ## Related Pages The core node type Configure your LLM provider Deploy to voice with streaming Test your flow # Testing Your Agent Source: https://docs.assistable.ai/build/flow-builder/testing Use Flow Builder's built-in test panel to simulate conversations and debug your flows. ## Overview Flow Builder includes a built-in test panel on the right side of the canvas where you simulate conversations before deploying to production. It connects directly to your flow's engine using your configured [API key](/build/flow-builder/api-key). ## Starting a Test Navigate to your flow in Flow Builder. See [Setting Up Your API Key](/build/flow-builder/api-key). The test drawer opens on the right. The start node fires automatically and you see the agent's opening message. Type messages and press Enter. Watch the canvas **highlight the active node** in real time — visual feedback showing exactly where your flow is. ## Key Features ### Reset Session Click **Reset** to clear the conversation, reset all variables, and return to the start node. Reset frequently — stale variable values can mask bugs. ### Conversation History The test drawer shows: * **Agent messages** — Responses from Conversation nodes * **User messages** — Your test inputs * **System events** — Node transitions, variable changes, API call results ### Variable Inspector Inspect the current state of all flow variables at any point. Use this to verify [Extraction nodes](/build/flow-builder/extraction-variable-nodes) capture data correctly. ### Voice Testing If configured for voice deployment, test how the agent sounds with TTS, validate interruption handling, and confirm speak-during-execution filler works during tool calls. ## Tips for Effective Testing * **Test edge cases** — Unexpected inputs, empty responses, off-topic messages * **Watch the canvas** — The highlighted node path shows routing correctness * **Check variables after extraction** — Use the variable inspector to confirm accuracy * **Test every branch** — Walk through all [Logic node](/build/flow-builder/logic-node) paths * **Reset between scenarios** — Don't rely on stale variable state If the test drawer shows no response, check that your API key is configured and your start node is set correctly. ## Related Pages Configure your LLM API key The core dialogue node How the engine processes turns Deploy to voice via Telnyx # Tool & Function Nodes Source: https://docs.assistable.ai/build/flow-builder/tool-function-nodes Execute pre-defined tools and make API calls from within your flow. ## Overview Flow Builder provides two node types for interacting with external services: the **Tool/Function node** for executing pre-defined tools, and the **Request node** for raw HTTP requests. Both integrate your flow with CRMs, booking systems, databases, and external APIs. ## Tool / Function Node The Tool/Function node executes an external tool defined at the flow level. Tools are reusable API integrations with defined parameters — pre-configured API calls you can drop into any flow. ### Parameter Mapping Map tool parameters to flow variables: | Tool Parameter | Mapped To | | ------------------ | ------------------- | | `customer_name` | `{{caller_name}}` | | `appointment_date` | `{{selected_date}}` | | `location_id` | `{{office_id}}` | ### Speak During Execution API calls take time. On voice calls, **silence is death**. The Speak During Execution feature fills dead air: | Mode | How It Works | Best For | | ---------- | --------------------------------------------- | ---------------------------- | | **Static** | Speaks fixed text (e.g., "One moment please") | Short, predictable waits | | **Prompt** | LLM generates contextual filler | Natural, personalized filler | Prompt-mode filler sounds much more natural on voice. Use static mode when speed is more important than personality. ### Sync vs Async * **Sync (default)** — Flow waits for the result. Use when the next node needs the tool's output. * **Async** — Tool runs in background. Use for non-blocking tasks like logging to CRM or sending emails. ## Choosing Between Tool/Function and Request Nodes | Use Case | Recommended | | ------------------------------ | ------------------------------------------------ | | Reusable integrations | Tool/Function | | One-off API calls | [Request Node](/build/flow-builder/request-node) | | Need speak-during-execution | Tool/Function | | Need fine-grained HTTP control | [Request Node](/build/flow-builder/request-node) | ## Related Pages Full HTTP request control Dynamic data and substitution The core dialogue node How the engine processes nodes # Variables & Dynamic Data Source: https://docs.assistable.ai/build/flow-builder/variables Store, transform, and inject dynamic values throughout your flow using the variable system. ## Overview Variables are the data layer of Flow Builder. They let you store, transform, and inject dynamic values throughout your flow — in prompts, URLs, headers, request bodies, and assignments. The syntax: wrap any variable name in double curly braces like `{{variable_name}}`. ## Substitution Syntax `{{variable_name}}` works everywhere text is accepted: | Where | Example | | -------------------- | ------------------------------------------- | | Conversation prompts | `You are speaking with {{caller_name}}` | | Request URLs | `https://api.example.com/users/{{user_id}}` | | Request headers | `Authorization: Bearer {{api_token}}` | | Request body | `{"email": "{{email}}"}` | | Variable assignments | `{{first_name}} {{last_name}}` | | Query parameters | `filter={{status}}&limit=10` | ## Variable Categories ### Right Now Date/time variables that resolve at runtime: * `{{current_date}}` — Today's date * `{{current_time}}` — Current time * `{{current_day}}` — Day of the week ### System Session-level variables populated automatically: * `{{session_key}}` — Unique session identifier * `{{flow_id}}` — ID of the running flow ### Flow Variables User-defined variables set via [Variable nodes](/build/flow-builder/extraction-variable-nodes), [Extraction nodes](/build/flow-builder/extraction-variable-nodes), or initialized via webhook. ### Node Outputs Automatically created by specific nodes: * **Extraction nodes** — Each extraction creates a variable * **Request nodes** — Creates `{{response}}`, `{{response_status}}`, `{{response_error}}` * **Tool/Function nodes** — Results via `{{_last_function_result}}` ## Special Variables | Variable | Description | | ----------------------------- | ------------------------------------------------------------- | | `{{_last_function_result}}` | Return value of the most recently executed Tool/Function node | | `{{responseVariable_status}}` | HTTP status from a Request node | | `{{responseVariable_error}}` | Error message from a failed Request node | ## Variables Webhook (Initialization) Configure a variables webhook at the flow level. When a new session starts, the engine calls this webhook **before the first node executes**. The response should return JSON key-value pairs: ```json theme={null} { "caller_name": "Sarah Johnson", "account_id": "ACC-4821", "plan": "premium", "language": "English" } ``` These variables are immediately available in your start node's prompt and throughout the flow. ## The VariablePicker UI Click the `{x}` icon in any field to open the VariablePicker — browse all available variables organized by category with search. ## Related Pages Set and extract variable values Branch based on variable values Use variables in API calls Use variables in prompts # Connecting Voice (Telnyx) Source: https://docs.assistable.ai/build/flow-builder/voice-connection Connect a Telnyx phone number to your flow for voice AI deployment. ## Overview Flow Builder supports voice deployment through **Telnyx**. Connect a phone number to your flow so inbound callers interact with your AI agent over a live phone call with real-time speech processing. ## How It Works 1. **Telnyx receives** the inbound call and forwards it to your flow's voice endpoint 2. **Flow Builder** processes each turn: speech-to-text → node execution → LLM call → response 3. **Responses stream** back via SSE for low-latency text-to-speech playback 4. **Conversation continues** until an End node is reached or the caller hangs up ## Setup Sign up at [telnyx.com](https://telnyx.com) and purchase a phone number. In Telnyx, set the phone number's webhook URL to your flow's voice endpoint (found in Flow Builder's deploy settings). Set the method to **POST**. Save the Telnyx configuration. Call your number to test the flow. ## Voice-Specific Best Practices | Consideration | Recommendation | | ------------------- | --------------------------------------------------------------- | | **Model selection** | Use fast models (`gpt-4o-mini`, `claude-haiku`) for low latency | | **Prompt length** | Keep prompts concise to reduce processing time | | **Static messages** | Use static mode for greetings/disclaimers to skip LLM | | **Tool calls** | Enable speak-during-execution filler to avoid dead air | ## Troubleshooting | Issue | Solution | | -------------------------- | ------------------------------------------------------------ | | Calls connect but no audio | Verify webhook URL matches your flow's voice endpoint | | Long pauses between turns | Use a faster LLM model and shorten prompts | | Agent doesn't respond | Confirm [API key](/build/flow-builder/api-key) is configured | | Call drops immediately | Check Telnyx webhook logs for connection errors | Test your flow thoroughly using the [built-in test panel](/build/flow-builder/testing) before connecting to a live phone number. ## Related Pages How streaming works for voice Test before deploying Deploy to chat instead Required for voice # Knowledge Base Source: https://docs.assistable.ai/build/prompting/knowledgebase Train your AI with company-specific information using the Knowledge Base. ## Overview The Knowledge Base provides company-specific information to your AI assistant. While the AI comes pre-trained with general knowledge, the Knowledge Base adds details specific to your business. ## Setting Up a Knowledge Base Navigate to the **Knowledge** tab in the left-hand menu (stack icon). Click the button in the top-right to create a new knowledge base. Name it appropriately. You can add data in several ways: **Manual Text Input:** Click "Add New Data Source" → "Text" and enter your content: ``` Apex Concrete serves Tucson, Arizona, offering: - Concrete Foundations - Driveways - Masonry Services Contact us at support@concrete.com ``` **FAQ Pairs:** Create precise Q\&A pairs for maximum accuracy. This is ideal for common questions with specific answers. **File Upload:** Upload documents containing your business information. **Website Scrape:** Point to a URL and let the system extract relevant content. Link the knowledge base to your assistant in the assistant builder settings. ## Best Practices * Use **FAQ format** for questions that need precise, consistent answers * Keep entries **focused and organized** by topic * **Update regularly** as your business information changes * Test by asking the AI questions that require knowledge base data * See [Knowledge Base Optimization](/troubleshooting/knowledge-base-optimization) for advanced tips # Prompt Engineering Tips Source: https://docs.assistable.ai/build/prompting/prompt-tips Best practices for writing effective AI assistant prompts that deliver consistent results. ## Task-Based Framework The most effective way to prompt your AI assistant is using a **task-based framework**. Instead of writing a single paragraph, break the assistant's job into sequential steps: ### Structure 1. **Identity** — Who the AI is, its name, role, and company 2. **Response Guidelines** — Tone, length, and style rules 3. **Style Guardrails** — What the AI should and shouldn't do 4. **Tasks** — Sequential objectives the AI should accomplish ### Example: Receptionist AI ``` Identity: You are Emma, a receptionist for Apex Concrete. Your role includes answering customer inquiries, qualifying leads, and scheduling appointments. You maintain a professional, approachable, and efficient tone. Response Guidelines: - Use concise and clear responses - Maintain a conversational, proactive, and helpful tone - Lead the conversation back to the topic if the user veers off-course - Use human-like phrasing with diverse language Tasks: 1. Greet the user warmly 2. Ask qualifying questions about their needs 3. Provide information about relevant services 4. Offer to book an appointment 5. Collect necessary contact information 6. Confirm the appointment details ``` ## Tips to Improve Performance * **Be specific** — Vague instructions produce vague responses * **Use examples** — Show the AI exactly how you want it to respond * **Set boundaries** — Tell the AI what it should NOT discuss * **Test iteratively** — Make small changes and test after each one * **Use variables** — Reference `{{contact.first_name}}` and other dynamic data * **Add fallbacks** — Tell the AI what to do when it doesn't know the answer # RAG Custom Databases Source: https://docs.assistable.ai/build/prompting/rag-databases Create custom RAG databases for Voice AI, Chat AI, and Web Orbs. ## What is RAG? RAG (Retrieval-Augmented Generation) allows your AI to search through custom databases of information at runtime. Instead of cramming everything into the prompt, the AI retrieves relevant content when it needs it. ## Creating a RAG Database RAG databases work across all assistant types: Voice AI, Chat AI, and Web Orbs. Go to the **Knowledge** section in your dashboard. Create a new knowledge base and select the RAG database option. Upload your data — documents, text entries, FAQs, or website content. The system indexes this for semantic search. Link the RAG database to your assistant. The AI will automatically search it when relevant questions arise. ## When to Use RAG vs. Standard Knowledge Base | Feature | Standard KB | RAG Database | | ----------- | --------------------------- | --------------------------- | | Best for | Small, focused datasets | Large, diverse content | | Retrieval | Full context in prompt | Semantic search at runtime | | Token usage | Higher (always loaded) | Lower (retrieved on demand) | | Accuracy | Very high for exact matches | High for broad topics | # Self-Selling Orb Demo Source: https://docs.assistable.ai/build/prompting/self-selling-orb Create an AI orb that demonstrates and sells your AI assistant services through roleplay. ## Overview The Self-Selling Orb is a powerful demo tool — an AI assistant embedded as a floating orb on your website that can conduct a roleplay demonstration of your AI services and even book appointments. This is perfect for: * Showing prospects what AI assistants can do * Running live demos on your website 24/7 * Booking sales calls automatically ## How It Works The orb acts as a sales assistant that: 1. Greets website visitors 2. Asks about their industry and needs 3. Conducts a roleplay showing how an AI assistant would work for their business 4. Offers to book a demo or consultation 5. Collects contact information ## Setting It Up Create a new assistant with the Self-Selling Orb prompt template, then deploy it as a [Floating Orb Widget](/deploy/widgets/orb-widget) on your website. Customize the prompt for your specific industry — solar, mortgage, dental, real estate, or any vertical you serve. # Call Forwarding Source: https://docs.assistable.ai/build/voice-ai/call-forwarding Forward unanswered calls to your AI assistant using GoHighLevel workflows. ## Overview This guide describes a workaround for forwarding unanswered calls in GoHighLevel to an AI assistant — a feature not directly available in GHL. This setup uses Twilio numbers and If-Else logic to route missed calls. ## Setup Steps * Assign a **primary Twilio number** (or LeadConnector number) for the human agent * Purchase a **second number** in your AI Assistant Dashboard for the AI fallback * Set the primary number as the user's inbound number * Configure a **call timeout** (e.g., 20 seconds) before the call is considered unanswered In GHL Automations, create a workflow called "Unanswered Call Forwarding": * **If call is answered** → End workflow * **If call status is "no answer"** → Route to AI assistant number Set up the AI assistant as a user in GHL with its assigned phone number, so it can receive forwarded calls. Call the primary number, let it ring past the timeout, and verify the call forwards to the AI assistant. ## FAQs Check that the timeout is correctly configured and the If-Else logic triggers only on "no answer" status. Yes, configure additional numbers and duplicate the workflow for each user. # Call Settings Source: https://docs.assistable.ai/build/voice-ai/call-settings Configure call duration limits, voicemail detection, and other call parameters. ## Call Duration Limit Set a maximum duration to automatically end calls that exceed the time limit. This feature helps: * Limit minutes spent on calls * Avoid large bills from spammers or stuck calls * Control costs across your sub-accounts ### Setting a Call Duration Limit 1. Navigate to **Call Settings** in the Assistant Builder 2. Enter the maximum call duration in minutes 3. Once the time limit is reached, calls are automatically terminated When the call reaches the duration limit, it will end immediately. Set an appropriate limit based on your typical call length. ## Call Configuration Options | Setting | Description | | ----------------------- | ------------------------------------------------- | | **Call Duration Limit** | Maximum call length in minutes | | **Voicemail Detection** | Automatically detect and handle voicemail systems | | **Voicemail Message** | Message to leave when voicemail is detected | | **Pre-Call Webhook** | URL to receive data when a call starts | | **Post-Call Webhook** | URL to receive call data after completion | | **Phone Number** | The number assigned to this assistant | # Call Transfers Source: https://docs.assistable.ai/build/voice-ai/call-transfers Set up your AI assistant to transfer calls to human agents or other numbers. ## Overview Your AI assistant can transfer active calls to human team members or other phone numbers. This requires creating a custom tool that specifies where to transfer and under what conditions. ## Setting Up Call Transfers Go to **Tools & Abilities** and select **Create New Tool**, then choose the **Transfer Call** option. Configure the transfer tool with: * **Phone number** to transfer to * **Conditions** under which transfer should occur * **Transfer type** (warm or cold) Remember to add the transfer tool to your assistant in the assistant builder's Tools section. ## Warm vs. Cold Transfers **Warm Transfer:** The AI provides context to the receiving agent before completing the handoff — who's calling, why, and a summary of the conversation. This creates a smoother experience for the caller. **Cold Transfer:** The call is simply forwarded without context. Use this when speed is more important than context. If the human agent is unavailable during a warm transfer, the AI can route the call elsewhere or offer to take a message. ## Dynamic Transfers You can configure the AI to **dynamically determine** where to transfer based on the conversation. Include a transfer matrix in your prompt with different numbers for different scenarios: ``` Transfer Matrix: - Billing questions → +1 (555) 111-2222 - Technical support → +1 (555) 333-4444 - Sales inquiries → +1 (555) 555-6666 - Emergency → +1 (555) 777-8888 ``` The AI will match the caller's needs to the appropriate transfer destination automatically. # Creating an AI Voice Assistant Source: https://docs.assistable.ai/build/voice-ai/creating-assistants Set up a voice-based AI assistant capable of booking appointments, handling calls, and managing customer interactions. ## Overview Voice AI assistants handle inbound and outbound phone calls autonomously. They can book appointments, answer questions, qualify leads, transfer calls, and more. ## Step-by-Step Setup Go to **Assistants** and click **Create New Assistant**. Choose your creation method: * **Generate Template** — Describe your use case and let AI create the prompt * **Blank Canvas** — Full manual control * **Import with ID** — Clone from another account Name your assistant and define its identity using a task-based framework. Set up your assistant's persona: * **Name and role** (e.g., "Katie, an appointment scheduler for ABC Dental") * **Response Guidelines** — Keep defaults for smooth conversational flow * **Style Guardrails** — Define tone and boundaries * **Tasks** — Use a task-based framework to give the AI sequential objectives Assign a phone number to your assistant: * **Buy a number** directly through the platform * **Import a number** from Twilio, Telnyx, or Vonage via SIP trunking * Ensure the number is compatible with SIP trunking if using an external provider Once assigned, your assistant can handle both inbound and outbound calls. If your assistant needs to manage appointments: 1. Go to calendar settings and select the appropriate calendars 2. Sync with GoHighLevel (or another calendar platform) 3. Run a calendar availability check to verify permissions 4. Enable all appointment actions: Check Availability, Book, Reschedule, Cancel, View Appointments Add tools for specific actions: * **Check Availability** — View open calendar slots * **Book Appointment** — Schedule appointments * **Reschedule Appointment** — Change existing bookings * **Cancel Appointment** — Remove appointments * **View Appointments** — List upcoming appointments Test each tool individually to confirm functionality. **Inbound test:** Call your assistant's number and test all functions. **Outbound test:** Create a GHL workflow with the **Make an AI Call** action and trigger it against a test contact. Verify appointments appear in your calendar and call logs are correct. ## Outbound Call Automation To automate outbound calls: 1. Go to **Automations** in GoHighLevel 2. Create a workflow with the **Make an AI Call** action 3. Enter your assistant's ID and call details 4. Test with a contact to verify the assistant performs as expected ## FAQs Yes, any provider supporting SIP trunking (e.g., Twilio, Telnyx, Vonage) is compatible. Ensure the calendar is fully synced and permissions are set correctly. Re-run the availability test to confirm. Yes, use the Response Guidelines and Style Guardrails sections, or edit the task-based framework in the prompt. # Voice Cloning Source: https://docs.assistable.ai/build/voice-ai/voice-cloning Clone custom voices and manage voice settings for your AI assistants. ## Voice Cloning Features Assistable.ai supports custom voice cloning so your AI assistant can sound exactly the way you want. ### Accessing the Voice Menu The voice settings menu is integrated directly into the assistant builder for easy access. You can: * Browse voices sorted by **age, gender, and accent** * Choose from multiple languages including French, Dutch, Vietnamese, and more * Vote on preferred voices to guide future platform updates ### Cloning a Voice Click **Clone Voice** in the voice settings section. Enter a descriptive name for the new voice. Upload a clear audio file of the voice you want to clone. Fill out the consent form confirming you have authorization to clone this voice. The system processes the file and the cloned voice appears in your account. This typically takes a few minutes. ### Copying a Voice by ID If you have an existing cloned voice in another sub-account: 1. Retrieve the **Voice ID** from the source account 2. Enter the Voice ID in the import field 3. The voice is duplicated to your account instantly You can share Voice IDs across accounts to maintain consistent branding across your agency. ## FAQs The cloning process is typically quick but may take a few minutes depending on server load. Yes, copy the Voice ID and share it with another account to import it. # Voicemail Handling Source: https://docs.assistable.ai/build/voice-ai/voicemail-handling Configure your AI assistant to detect and handle voicemail systems during calls. ## Overview Your AI assistant can automatically detect voicemail systems and respond appropriately — either hanging up or leaving a customized message. The system runs voicemail detection in the background during calls. You have full control over the behavior: * **No voicemail message configured** → AI hangs up when voicemail is detected * **Voicemail message configured** → AI waits for its turn and delivers the message If the voicemail detection timeout is reached without detecting voicemail, the call continues as normal. ## Enabling Voicemail Detection Inside your assistant's **Call Settings**, toggle **Enable Voicemail & Message**: * **Hang up on voicemail** — If no message is provided, the AI simply disconnects when it detects voicemail * **Leave a voicemail** — Customize the message using variables and dynamic inputs to personalize it based on the call context Use variables like `{{contact.first_name}}` in your voicemail message to make it personal and contextual. ## Best Practices * Keep voicemail messages concise (under 30 seconds) * Include a callback number or next step * Use the `voicemail reached` tag in your workflows to track how many calls go to voicemail * Consider different strategies for inbound vs. outbound call voicemail handling # Changelog Source: https://docs.assistable.ai/changelog New features, improvements, and fixes across Assistable.ai Follow new releases via the [RSS feed](/changelog/rss.xml) or the **#announcements** channel in our [Discord](https://discord.gg/5v4WSM3YwP). Assistable now supports Cartesia as a voice provider, adding 773 natural-sounding voices across more than 50 languages. * Choose Cartesia voices when configuring any assistant * Audition voices before saving to hear the exact output quality * Tune Voice Speed and Expressive Mode for every Cartesia voice * Existing assistants and voices remain unchanged [Read the guide](/v3/voice-studio) Starting September 11, 2026, text-to-speech usage will be billed and tracked separately from voice orchestration usage. * Configure TTS rebilling separately for each sub-account with fixed rates or percentage markups * Rebill TTS independently from orchestration charges * View TTS charges itemized separately in billing records and transaction logs * No action required before September 11, but review your sub-account billing settings after the release to ensure your TTS pricing and margins are configured correctly [Read the guide](/platform/rebilling) Assistable now connects to 8,000+ apps through Zapier. No code, no webhooks to babysit. * **5 triggers** including New Call with status and sentiment filters, and New Monitor Alert * **13 actions** including Place AI Voice Call, Generate AI Reply, and Add to Knowledge Base * **4 searches** including Find-or-Create Contact and Get Call by ID with full transcript * Connects with a [v3 API key](/v3/authentication) in about a minute * Invite-only beta: [Add Assistable to your Zapier account](https://zapier.com/developer/public-invite/243635/9ed48f96fb7ec82f2581603b9d77eac3/) * Found a rough edge? Tell us in [Discord](https://discord.gg/5v4WSM3YwP) #get-help and we will ship the fix [Read the full guide](/v3/zapier) The voice pipeline is now multi-provider: five new text-to-speech engines, six new speech-to-text models, and noise suppression, all in a redesigned Voice Studio. * **Five new TTS providers**: Amazon Polly, Microsoft Azure, Inworld (Mini/Max), Resemble (Turbo/Rapid), plus expanded Rime models (Coda, Natural, Natural HD, Arcana v3, Kokoro) and MiniMax speech-2.8-turbo and speech-2.5-hd. * **Six new transcription engines**: Deepgram Flux (new recommended default with fine-grained end-of-turn controls), Deepgram Nova-3 (80+ languages, Smart Format, Keyterm Boost), Deepgram Nova-2, AssemblyAI Universal-Streaming, Azure Fast. * **Noise suppression**: Krisp (recommended) or DeepFilterNet with adjustable attenuation, cleaning up caller audio from cars, cafés, and job sites before it reaches transcription. * **Redesigned Voice Studio**: Voice Settings panel (provider/model selection, voice tuning, transcription, noise suppression, interruption controls, auto-save with Publish workflow), Voice Library (instant search, filters, Recommended/Favorites tabs, one-click previews, community voting), Compare dock (shortlist up to 8 voices, back-to-back playback with adjustable speed, one-click apply), My Voices (import, clone, duplicate by ID). * **Expressive Mode**: context-aware emotion and Language Boost across 11 languages for supported providers. * **ElevenLabs fine-tuning**: Stability, Similarity Boost, Style, Speaker Boost controls for Eleven v2, Flash v2/v2.5, Turbo v2/v2.5, Multilingual v2. Open any assistant, go to Voice Settings, click Change voice to explore the new providers, pick a transcription model and noise suppression engine, and press Publish when ready. [Read the full guide](/v3/voice-studio) The Chat Widget now supports live voice conversations alongside text chat. Visitors can switch between typing and speaking mid-conversation, with the assistant maintaining full context across both modes. * **Chat | Voice toggle**, one-tap switch between text and voice, with seamless context handoff when switching mid-conversation * **Unified knowledge base**, voice answers from the same knowledge base as chat, with context-aware follow-ups and multi-angle search * **Action cards**, interactive cards for products, orders, tickets, bookings, and feedback instead of text-only responses * **Human handoff**, three modes (support, transparent, disabled) with live-agent indicators and office hours * **Home tabs**, lobby with action cards, news feed, roadmap, and live knowledge base search * **Pre-chat forms**, optional name/email/phone collection before conversation starts [Read the full guide](/v3/voice-enabled-chat-widget) Assistable's billing is now fully documented in a comprehensive guide covering every charge type, rebilling mechanics, and real pricing examples. * Complete breakdown of voice call pricing (voice engine, LLM, telephony, short-call surcharge) with per-second billing math * Chat message, knowledge base, observation/QA, and phone number pricing explained with worked examples * Full rebilling guide for agencies: how to set fixed prices vs. percentage markups, what clients see, and profit calculation examples * Transaction receipt anatomy and FAQ covering common billing questions [Read the full guide](/v3/billing-guide) Build on Assistable programmatically. The v3 REST API ships with scoped API keys, predictable rate limits, and a full interactive [API Reference](/v3/introduction) — plus official tooling for every workflow: * **[TypeScript SDK](/v3/typescript-sdk)** — `npm install @assistableai/sdk`. Typed operation functions for every v3 endpoint. * **[Python SDK](/v3/python-sdk)** — `pip install assistableai`. Typed models with sync and async variants. * **[MCP server](/v3/mcp-server)** — `@assistableai/mcp` exposes every v3 operation as a tool for Claude Desktop, Cursor, and other MCP clients. * **[CLI](/v3/cli)** — `@assistableai/cli` puts every v3 operation in your terminal and CI scripts. * **[Export & Test](/v3/export)** — download the OpenAPI spec or a ready-to-run Postman collection and start sending requests in seconds. The official Assistable Discord is live — [join here](https://discord.gg/5v4WSM3YwP). * **#ask-ai** — an AI support assistant that answers from these docs, with cited sources. * **#get-help** — a support forum where the assistant posts a first response on every thread and routes bugs straight to the team. * **#announcements** and **#status** — release news and platform status; hit **Follow** to mirror either channel into your own server. Real-time platform status also lives at [status.assistable.ai](https://status.assistable.ai). And this changelog is new too — subscribe to the [RSS feed](/changelog/rss.xml) to get every update. # Active Tags for Phone Numbers Source: https://docs.assistable.ai/deploy/telephony/active-tags Use active tags to control which assistant handles calls and enable outbound calling. ## Overview Active tags connect contacts to specific AI assistants. When a tag is present on a contact, the system knows which assistant should handle the interaction. ## For Voice AI Active tags work with phone numbers to: * Route inbound calls to the correct assistant * Enable outbound calling campaigns * Track which contacts are actively being managed by AI ## Setup 1. Go to **Active Tags** in your dashboard 2. Create a new tag with a unique name 3. Link it to an AI assistant and phone number 4. Apply the tag to contacts via GHL workflows Use descriptive tag names like `ai_voice_receptionist` or `ai_outbound_sales` to keep things organized across multiple assistants. # Buy Phone Numbers Source: https://docs.assistable.ai/deploy/telephony/buy-numbers Purchase phone numbers directly through the Assistable platform. ## Overview You can buy phone numbers directly from within Assistable to use with your AI assistants for both inbound and outbound calling. ## Steps Go to the **Numbers** section in your dashboard or within an assistant's settings. Click **Buy Number** and select from available numbers. Choose based on area code preference. Once purchased, assign the number to your AI assistant in the assistant's call settings. Purchased numbers work immediately for both inbound and outbound calls. No additional SIP trunking configuration is required. ## Alternative: Import Numbers If you already have numbers with Twilio, Telnyx, or Vonage, you can import them via SIP trunking: # Import Telnyx Numbers Source: https://docs.assistable.ai/deploy/telephony/import-telnyx Connect your Telnyx phone numbers to Assistable via SIP trunking. ## Overview Import Telnyx numbers using SIP trunking. This guide walks through FQDN-based trunk setup. ## Step-by-Step Setup Log in to Telnyx → **SIP Connections** → **Create SIP Connection**. Choose **FQDN** as trunk type. In the FQDNs section under Authentication and Routing: * Add FQDN: `5t4n6j0wnrl.sip.livekit.cloud` * Set DNS record type to **SRV** Under **Outbound Calls Authentication**: * Choose **Credentials** as method * Set a username and password (save these for later) * Allow inbound calls in **+E.164 format** (critical — wrong format causes inbound failures) * Choose codecs: **G722, G729, and OPUS** * Select the region closest to you Create a new **Outbound Voice Profile** and select it in the dropdown. Gather your raw phone number, SIP username, password, and URI (`sip.telnyx.com`), then import in the Assistable dashboard. Double-check that the inbound format is set to +E.164 and the outbound URI is correct — incorrect values are the most common cause of call failures. ## Troubleshooting If calls aren't working, verify all steps above are done correctly. Assistable stores the SIP info you provide to build the SIP packet — whether calls connect depends on your Telnyx configuration. Contact Telnyx support for provider-side issues. # Import Twilio Numbers Source: https://docs.assistable.ai/deploy/telephony/import-twilio Connect your Twilio phone numbers to Assistable via Elastic SIP Trunking. ## Overview Import your existing Twilio numbers into Assistable using Elastic SIP Trunking. This connects Twilio's VoIP system to the platform so your AI can make and receive calls. ## Step-by-Step Setup Log in to [console.twilio.com](https://console.twilio.com) and navigate to **Explore Products** → **Super Network** → **Elastic SIP Trunking**. Click **Get Started** → **Create a SIP Trunk**. Give it a name and create it. * Enable **Call Recording** (Record from ringing) * Enable **Call Transfer** (SIP REFER) * Set Caller ID for Transfer Target to **caller ID as transferee** * Click **Save** Go to **Termination** in the left navigation. Save the **Termination SIP URI** — you'll need it later. Under **Authentication** → **IP Access Control Lists**, add two entries: * **default ACL 1**: Address `0.0.0.0/1` * **default ACL 2**: Address `128.0.0.0/1` Go to **Origination** and add this URI: ``` sip:ecabe71af1354f858dc49374b8293591.sip.telnyx.com ``` Click **Add a number** in the top right. Buy a new number or add an existing one to this trunk. In your Assistable dashboard: 1. Go to **Numbers** → **Import a Number** 2. Enter the number in raw format: `+1XXXXXXXXXX` (no spaces or special characters) 3. Enter your **Termination URI** 4. Click **Import** The system saves your Termination URI for future imports. Both the IP Access Control Lists (for outbound) and the Origination URI (for inbound) must be configured correctly, or calls will fail. # Import Vonage Numbers Source: https://docs.assistable.ai/deploy/telephony/import-vonage Connect your Vonage phone numbers to Assistable via SIP trunking. ## Overview Import Vonage numbers using SIP trunking. This process works with any provider that supports SIP trunking. ## Setup Steps Log in to Vonage → **SIP** tab → Create a new SIP trunk. Copy your **URI, username, and password** from the termination section. Set the origination address to: `5t4n6j0wnrl.sip.livekit.cloud` Move existing numbers into the trunk or purchase new ones. Enter the raw phone number (with country code), trunk URI, and authentication credentials in the Assistable import form. ## Troubleshooting Common issues to check: * Is your account verified? * Is the number in raw E.164 format? * Are there country-specific regulations requiring additional setup? Contact your provider's support for deeper troubleshooting. # Inbound Calls Source: https://docs.assistable.ai/deploy/telephony/inbound-calls Configure your AI assistant to handle incoming phone calls. ## Overview When a phone number is assigned to an AI assistant, all inbound calls to that number are automatically handled by the AI. The assistant follows its prompt and configured tools to manage the conversation. ## Setup 1. **Assign a number** to your assistant (buy or import) 2. **Configure the prompt** with appropriate greeting and tasks 3. **Enable calendar tools** if the assistant needs to book appointments 4. **Set up webhooks** if you need pre-call or post-call automation ## Call Flow 1. Caller dials your AI assistant's number 2. AI picks up and delivers its greeting 3. Conversation proceeds based on the prompt and tools 4. Call ends → post-call webhook fires with transcript, summary, and metadata 5. Tags are automatically applied to the contact based on call outcome ## Tips * Test inbound calls thoroughly before going live * Set a [call duration limit](/build/voice-ai/call-settings) to prevent runaway calls * Enable [voicemail detection](/build/voice-ai/voicemail-handling) if needed * Set up [pre/post-call webhooks](/deploy/webhooks/pre-post-call) for workflow automation # Outbound Calls Source: https://docs.assistable.ai/deploy/telephony/outbound-calls Initiate AI-powered outbound calls through GoHighLevel workflows. ## Overview Outbound calls are initiated through GoHighLevel workflows using the **Make an AI Call** action. The AI assistant calls the contact and follows its prompt to complete tasks. ## Common Issues If your AI isn't making calls, check these common causes: ### Wallet Balance * **Agency owners**: Ensure your [agency wallet](/platform/agency-wallet) has a positive balance. A negative balance stops calls for ALL sub-accounts. * **Sub-account users**: Ensure your [sub-account wallet](/platform/subaccount-wallet) is funded. ### Phone Number The assistant must have a phone number linked to it. ### DNC Compliance The number you're calling may be on a Do Not Call list. Learn more about [DNC compliance](/monitor/dnc-compliance). ## Automation Setup 1. Go to **Automations** in GoHighLevel 2. Create a workflow with the **Make an AI Call** action 3. Enter your assistant's ID 4. Set the trigger (form submission, tag added, scheduled time, etc.) 5. Test with a contact to verify # Pre-Call & Post-Call Webhooks Source: https://docs.assistable.ai/deploy/webhooks/pre-post-call Set up webhooks to trigger automations before and after AI calls. ## Overview Webhooks notify your systems when calls start and end. They enable pre-call tracking and post-call automation in GoHighLevel. * **Pre-Call Webhook** — Fires when an AI call initiates (inbound or outbound) * **Post-Call Webhook** — Fires after a call ends with full call data ## Webhook Payloads ### Pre-Call Payload ```json theme={null} { "to": "+15551234567", "from": "+15559876543", "contactId": "contact_abc123" } ``` ### Post-Call Payload ```json theme={null} { "call_id": "call_xyz", "call_type": "voice", "direction": "outbound", "to": "+15551234567", "from": "+15559876543", "contact_id": "contact_abc123", "disconnection_reason": "completed", "user_sentiment": "positive", "call_summary": "Customer booked an appointment for Friday at 2 PM.", "call_completion": "complete", "assistant_task_completion": "success", "recording_url": "https://...", "call_time_ms": 145000, "call_time_seconds": 145, "full_transcript": "...", "start_timestamp": "2026-02-27T14:30:00Z", "end_timestamp": "2026-02-27T14:32:25Z" } ``` ## Setup Steps In GHL: **Automations** → **Create Workflow** → **Start from Scratch** * Add **Inbound Webhook** trigger * Copy the webhook URL * Paste it into your assistant's **Call Settings** → **Pre-Call Webhook** * Click the checkmark to confirm connection * Fetch Sample Request to load example data * Add a **Find Contact by Contact ID** action using the webhook's `contact_id` Create another workflow for post-call data: * Add **Inbound Webhook** trigger * Copy and paste URL into assistant's **Post-Call Webhook** field * Fetch Sample Request * Add **Find Contact by Contact ID** action * Add actions to update custom fields (transcript, summary, etc.) In GHL Settings → Custom Fields, create: * **Conversation Summary** (Multi-line Text) * **AI Conversation Transcript** (Multi-line Text) Map these fields in your post-call workflow. You can optionally add a **Note** action to the post-call workflow to log call summaries, sentiment, and call IDs directly to the contact's notes. # Chat Widget Source: https://docs.assistable.ai/deploy/widgets/chat-widget Embed an AI chat widget on your website for text-based conversations. ## Overview The Chat Widget enables text-based AI conversations on your website. Visitors can chat with your AI assistant without making a phone call. ## Setup Go to **Widgets** → **Create Widget** → **Chat Widget**. Assign the widget to your AI assistant and customize appearance settings. Copy the embed code and paste it into your website's HTML. For Flow Builder-based chat widgets, see [Embedding the Chat Widget](/build/flow-builder/embedding-widget). # Voice Orb Widget Source: https://docs.assistable.ai/deploy/widgets/orb-widget Install a floating AI voice orb on your website for interactive visitor engagement. ## Overview The AI Orb is a floating, clickable widget that launches your AI assistant when a visitor clicks it. It enables voice-based sales conversations, demos, and appointment booking directly from any website. ## Setup Build the AI assistant that will power the orb. Configure its prompt, voice, and calendar tools. Purchase a phone number and assign it to your assistant. Visitors won't see this number. Go to **Widgets** → **Create Widget** → **Floating Orb**. Name it and configure: * Assign it to your assistant * Customize the icon (phone, robot, etc.) * Set the color * Save changes Click **Get Code** at the bottom of the widget settings. Copy the embed code. In your website builder: 1. Add a **Custom Code** or **HTML** element 2. Paste the embed code 3. Save and publish your site Visit your live site, click the orb, and verify the AI assistant launches correctly. ## FAQs Yes — any site that allows you to embed HTML. No, the number is hidden since the interaction happens through the web interface. No, just copy and paste the embed script. # Assistable Direct Source: https://docs.assistable.ai/direct/overview Run Assistable as your own CRM — provision accounts, manage users, fund wallets, and drive AI conversations with zero GoHighLevel. **Assistable Direct** is Assistable with its own native CRM. A Direct sub-account stores its contacts, conversations and messages in Assistable itself — there's no GoHighLevel (or any external CRM) in the loop. You provision accounts, add users, fund wallets and talk to assistants entirely over the API. Direct runs on the same `/v3` endpoints as the rest of the platform, so everything you already know about the [v3 API](/v3/introduction) applies — the auth model, the response envelope, rate limits and the interactive reference. This section collects the pieces that are specific to Direct. ## How it fits together `POST /v3/subaccounts` creates a native sub-account and returns a webhook URL + secret. See [Provisioning](/direct/provisioning). Invite people to the sub-account with `POST /v3/subaccounts/{id}/users` — passwords are stored bcrypt-hashed, never in plain text. Credit the wallet so the account can run chat and voice. See [Wallets](/direct/wallets). Forward inbound messages to the Direct listener; Assistable auto-creates the contact + conversation and replies with the bound assistant. See [Webhook ingestion](/direct/webhooks). Assistants, contacts, conversations, chat, knowledge, tools, calls, numbers, alerts and monitor-rules all work against a Direct sub-account exactly as they do elsewhere — scoped by `X-Subaccount-Id`. Browse them in the **API Reference** tab. ## What's different on Direct * **Native CRM** — contacts, conversations and messages live in Assistable, not GHL. * **Provisioning API** — create sub-accounts, users and wallets programmatically (the `Subaccounts` resource). * **Authenticated inbound webhook** — one signed endpoint ingests messages and triggers an AI reply. Appointments are not yet available on Direct — that resource is still GoHighLevel-scoped. Everything else in v3 works on a Direct sub-account. # Provisioning Source: https://docs.assistable.ai/direct/provisioning Create a Direct sub-account and manage its users over the API. Provisioning is a workspace-level operation: the API key's workspace owns every Direct sub-account you create. You'll need a key with the `subaccounts:create` scope. ## Create a sub-account `POST /v3/subaccounts` creates a native (GHL-free) sub-account plus its inbound webhook integration, and returns the webhook URL and secret. ```bash theme={null} curl https://api.assistable.ai/v3/subaccounts \ -H "Authorization: Bearer ask_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Direct" }' ``` ```json theme={null} { "data": { "id": "sub_123", "name": "Acme Direct", "integrationType": "ASSISTABLE_DIRECT", "integrationId": "int_123", "webhookUrl": "https://api.assistable.ai/listener-assistable-direct", "webhookSecret": "whsec_…", "createdAt": "2026-06-18T00:00:00.000Z" }, "error": null, "request_id": "req_…" } ``` `webhookSecret` is returned **once**, only in this create response. Store it now — it's never shown again. Use it to authenticate the [inbound webhook](/direct/webhooks). ## Manage users A user belongs to a sub-account through a role (`OWNER`, `ADMIN`, `MEMBER`, or `VIEWER`). These endpoints need the `subaccounts:update` scope (and `subaccounts:read` to list). ```bash theme={null} curl https://api.assistable.ai/v3/subaccounts/sub_123/users \ -H "Authorization: Bearer ask_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "email": "jane@acme.com", "password": "s3cret-passw0rd", "role": "ADMIN" }' ``` The password is stored as a bcrypt hash (cost 12) — never in plain text. If the email already belongs to a platform user, that user is linked to the sub-account and their existing password is left untouched. * `GET /v3/subaccounts/{id}/users` — list active members. * `PATCH /v3/subaccounts/{id}/users/{userId}` — change a member's role. * `DELETE /v3/subaccounts/{id}/users/{userId}` — remove a member (soft). Removing a member only unlinks them from the sub-account — the underlying user account is never deleted. You can't remove the **last** owner; that returns `409 last_owner`. # Wallets Source: https://docs.assistable.ai/direct/wallets Fund and adjust a Direct account's wallet so it can run chat and voice. A Direct account spends from a wallet to run chat and voice. There are two balance planes: * **Workspace wallet** — what the spend gate reads. **Fund this** to let the account actually run AI. * **Sub-account wallet** — a per-sub balance you can track separately. All amounts are integer **cents**. The wallet endpoints need the `billing:read` scope (balance) and `billing:update` scope (credit/debit) — a key with only `subaccounts:*` scopes cannot move funds. ## Check balances ```bash theme={null} curl https://api.assistable.ai/v3/subaccounts/sub_123/wallet \ -H "Authorization: Bearer ask_live_xxx" ``` ```json theme={null} { "data": { "subAccountId": "sub_123", "subAccountBalanceCents": 2500, "subAccountBalanceDollars": 25, "workspaceBalanceCents": 10000, "workspaceBalanceDollars": 100 }, "error": null, "request_id": "req_…" } ``` ## Credit a wallet ```bash theme={null} curl https://api.assistable.ai/v3/subaccounts/sub_123/wallet/credit \ -H "Authorization: Bearer ask_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "amount_cents": 5000, "target": "workspace", "idempotency_key": "topup-2026-06-18-a" }' ``` | Field | Required | Notes | | ----------------- | -------- | -------------------------------------------------------------------------------------------------- | | `amount_cents` | yes | Amount to move, in integer cents (1–100,000,000). | | `target` | no | `workspace` (default — the spend-gate plane) or `subaccount`. | | `description` | no | Audit note stored on the ledger transaction. | | `idempotency_key` | yes | Repeating a credit/debit with the same key returns the original result without moving funds again. | The response reports the resulting balance and whether it was an idempotent replay: ```json theme={null} { "data": { "subAccountId": "sub_123", "target": "workspace", "direction": "credit", "amountCents": 5000, "balanceCents": 15000, "balanceDollars": 150, "replayed": false }, "error": null, "request_id": "req_…" } ``` ## Debit a wallet `POST /v3/subaccounts/{id}/wallet/debit` takes the same body and claws funds back. A debit can **never** drive a balance negative — if the target plane doesn't have enough, it returns `409 insufficient_balance` and no funds move. The `idempotency_key` is required on every credit and debit. If a request times out and you retry with the same key, the wallet moves exactly once. # Webhook ingestion Source: https://docs.assistable.ai/direct/webhooks Forward inbound messages to a Direct sub-account and get an AI reply — native contact, conversation and message, zero GHL. Direct sub-accounts receive messages through one authenticated endpoint. Post a message to it and Assistable resolves (or creates) the native contact and conversation, stores the message, and runs the bound assistant to reply. ``` POST https://api.assistable.ai/listener-assistable-direct ``` This endpoint lives at the platform root (not under `/v3`) and is authenticated by the sub-account's **webhook secret**, not your API key — so an external CRM or your own backend can call it directly. ## Authentication Send the `webhookSecret` from the [create-sub-account](/direct/provisioning) response as either header: ```bash theme={null} # either -H "x-assistable-webhook-secret: whsec_…" # or -H "Authorization: Bearer whsec_…" ``` A bad or missing secret returns `401`. The secret is compared in constant time. ## Request body ```json theme={null} { "subAccountId": "sub_123", "body": "Hi, is anyone there?", "channel": "SMS", "direction": "inbound", "externalMessageId": "msg_abc", "contact": { "phone": "+15551234567", "firstName": "Jane", "email": "jane@acme.com" } } ``` | Field | Required | Notes | | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------- | | `subAccountId` | yes | The Direct sub-account receiving the message. | | `body` | yes | Message text. Empty bodies are rejected. | | `contact` | yes | One of `id`, `phone`, or `email` to resolve/create the contact (`firstName`, `lastName`, `name` optional). | | `channel` | no | e.g. `SMS`, `Chat`, `Email`. Defaults to `Chat`. | | `direction` | no | `inbound` (default) or `outbound`. | | `externalMessageId` | no | Your id for the message; used to de-duplicate retries. | | `conversationId` | no | Target an existing native conversation; otherwise resolved per contact + channel. | ## What happens next The contact is resolved (by `id` → `phone` → `email`) or created, the conversation is found-or-created, and the message is stored natively. Human-takeover and sleep gates are checked, and the conversation is bound to the sub-account's active assistant. The assistant runs and the reply is written back as a native message (and emitted on the `message.sent` webhook). No GoHighLevel is involved. Re-posting the same `externalMessageId` for a sub-account within a short window is de-duplicated, so safe retries won't create duplicate messages. # Introduction Source: https://docs.assistable.ai/get-started/introduction Build, deploy, and manage AI voice and chat assistants at scale. Assistable agent builder — global prompt, identity, response frameworks, and tool kit sidebar > 🤖 Build intelligent AI assistants that handle phone calls, SMS, and live chat — all from one platform. Powering 70M+ conversations for 8,000+ businesses. **Assistable.ai** is the leading AI assistant platform built for agencies, franchises, and businesses that need to deploy conversational AI at scale. Whether you're managing hundreds of sub-accounts or launching a single AI receptionist, Assistable gives you the tools to build, deploy, and monitor AI assistants across voice, chat, and web channels. ## Two Products, One Platform Built for **agencies and franchises** managing multiple clients through GoHighLevel. Manage sub-accounts, set up rebilling, white-label the platform, and deploy AI assistants across your entire portfolio. Built for **businesses** deploying AI assistants directly. Get started quickly without the agency layer — perfect for companies that want AI-powered calling, chat, and web assistants for their own operations. ## What Can You Build? Create AI assistants that make and receive phone calls, book appointments, transfer calls, and handle voicemail — all with natural-sounding voices. Deploy AI that responds to SMS, live chat, and web conversations automatically using active tags — no workflows or API calls required. Design complex conversational flows with a visual drag-and-drop builder. Add logic, API calls, variables, and more. Extend your AI with custom API integrations — update CRM records, search the web, calculate distances, scrape websites, and more. ## Explore the Docs Build your first AI assistant in minutes. Connect phone numbers and launch widgets. Track call outcomes, errors, and compliance. Manage your agency workspace and sub-accounts. Connect to GoHighLevel and more. Build with the Assistable API. # Platform Overview Source: https://docs.assistable.ai/get-started/platform-overview Understand how Assistable.ai is structured — workspaces, sub-accounts, assistants, and more. ## Architecture Assistable.ai is designed around a **workspace → sub-account → assistant** hierarchy that mirrors the GoHighLevel (GHL) structure most agencies already use. ### Workspace (Agency Level) The workspace is your top-level account. As the workspace owner, you can: * Manage all sub-accounts from a single dashboard * Set up rebilling to charge clients for AI usage * White-label and brand the portal * Control sub-account permissions and limits * Configure agency-wide snapshots for new sub-accounts ### Sub-Accounts (Client Level) Each sub-account represents a client or business unit. Sub-accounts have their own: * AI assistants (voice and chat) * Phone numbers * Knowledge bases * Custom tools * Wallet balance * Active tags for chat automation ### Assistants Assistants are the AI agents that handle conversations. Each assistant has: * A prompt defining its identity, tasks, and behavior * Connected tools (calendar booking, custom tools, knowledge base) * Call settings (phone number, voicemail handling, call duration limits) * Active tags for chat activation ## Key Concepts | Concept | Description | | ------------------ | -------------------------------------------------------------------------------------------------- | | **Active Tags** | Tags applied to contacts that activate AI chat responses. No Active Tag = AI is silent. | | **Custom Tools** | API-powered extensions that let the AI perform actions (update CRM, search web, book appointments) | | **Knowledge Base** | Company-specific information the AI uses to answer questions accurately | | **Flow Builder** | Visual drag-and-drop builder for creating complex conversational flows | | **Webhooks** | Pre-call and post-call webhooks that trigger GHL workflows with call data | | **SIP Trunking** | How external phone numbers (Twilio, Telnyx, Vonage) connect to the AI platform | | **Rebilling** | Agency feature to charge sub-accounts for AI usage via Stripe | ## Assistable vs. Assistable Direct | Feature | Assistable (Multi-Tenant) | Assistable Direct | | ---------------------- | --------------------------------------- | ----------------------------- | | Target User | Agencies & Franchises | Individual Businesses | | GHL Integration | Full workspace + sub-account management | Direct sub-account connection | | White Labeling | ✅ Full portal branding | N/A | | Rebilling | ✅ Charge clients via Stripe | N/A | | Sub-Account Management | ✅ Manage unlimited clients | Single account | | Snapshots | ✅ Template new sub-accounts | N/A | ## Next Steps Follow the quickstart guide. Configure your agency workspace. # Quickstart Source: https://docs.assistable.ai/get-started/quickstart Build and deploy your first AI assistant in under 10 minutes. > 🚀 Go from zero to a working AI voice assistant in minutes. This guide walks you through creating your first AI assistant, assigning a phone number, and making a test call. Navigate to the **Assistants** section in your dashboard and click **Create New Assistant**. You can: * **Generate Template** — Use AI to generate a prompt based on your description (recommended for beginners) * **Blank Canvas** — Start from scratch with full control * **Import with ID** — Copy an existing assistant from another account Give your assistant a name, define its identity (e.g., "Emma, a receptionist for Acme Corp"), and set up its tasks. In the assistant builder, set up: * **Identity** — Who the AI is and what it does * **Tasks** — Sequential steps the AI should follow (greet, qualify, book appointments, etc.) * **Response Guidelines** — Tone, style, and guardrails * **Knowledge Base** — Upload company-specific information (services, hours, pricing, FAQs) Use the task-based framework to give your AI clear objectives. This produces much better results than a single paragraph prompt. Go to the **Numbers** section and either: * **Buy a number** directly through the platform * **Import a number** from Twilio, Telnyx, or Vonage via SIP trunking Assign the number to your assistant in the assistant's call settings. If your assistant needs to book appointments: 1. Go to Calendar settings and sync your calendar 2. Enable the built-in calendar tools: Check Availability, Book Appointment, Reschedule, Cancel 3. Test the calendar connection to verify available time slots **Inbound test:** Call your assigned number and have a conversation with your AI. **Outbound test:** Create a GHL workflow with the **Make an AI Call** action, enter your assistant ID, and trigger it against a test contact. Verify that the assistant responds correctly and any bookings appear in your calendar. ## What's Next? Give your assistant a custom voice. Extend your AI with API integrations. Add a voice orb to your website. Track outcomes and optimize. # Appointment Deposits Source: https://docs.assistable.ai/how-to-guides/appointment-deposits Automate appointment deposit collection to reduce no-shows using GoHighLevel workflows. ## Overview Automate deposit collection when clients book appointments. This reduces no-shows and streamlines the booking process using GoHighLevel's payment system and workflow automation. ## Setup 1. Go to **Payments > Products** in GoHighLevel 2. Click **+ Create Product** 3. Name: "Appointment Deposit" 4. Type: Digital Good / Service 5. Price: Your desired amount (e.g., \$50) 6. Save 1. Go to **Payments > Payment Links** 2. Click **Create Payment Link** 3. Select your deposit product 4. Copy the generated URL 1. Go to **Automation > Workflows > Create New** 2. Trigger: **Appointment Status → Confirmed** 3. Action: **Send SMS**: *"Hi \{\{contact.first\_name}}, your appointment is reserved! Secure your spot: \[Payment Link]"* 4. (Optional) Add a **Wait** step + reminder if unpaid after 24 hours 1. Create a second workflow 2. Trigger: **Order Submitted** (filter: Appointment Deposit product) 3. Action: **Send SMS/Email**: "Thank you! Your deposit is received. Your appointment is fully secured." 4. Action: **Update Contact Tag** → "Deposit Paid" ## Related Pages Automate no-show follow-ups Send conversation transcripts Book across multiple calendars # Auto-Populate Custom Fields Source: https://docs.assistable.ai/how-to-guides/auto-populate-fields Automatically populate GoHighLevel custom fields using AI-powered data collection. ## Overview Configure **Automatic Data Collection** in GoHighLevel to auto-fill custom fields using AI — without live tool calls. This captures data from voice calls (post-call) and chat interactions (per run), reducing manual input and eliminating tool call latency. ## Setup Open any contact in GoHighLevel. Scroll to the **Automatic Data Collection** section. Click **Create New** and configure: * **Name**: Lowercase, no spaces (e.g., `business_ein`) * **Data Type**: `string` (most cases), `number`, or `boolean` * **Description**: What to capture (e.g., "User's Business EIN") * **Mapping**: Link to the appropriate custom field Send a test message (e.g., "Our CAC is $25 and LTV is $3,200") or complete a voice call. No tool call is triggered — latency stays normal. Refresh the contact to verify mapped fields are auto-filled. This method works alongside [Data Extraction](/how-to-guides/data-extraction) — use whichever approach fits your use case better. ## Related Pages Assistable's extraction approach Save addresses via custom tools Update CRM contacts # Data Extraction Source: https://docs.assistable.ai/how-to-guides/data-extraction Gather and extract important user information using Assistable's automatic data extraction. ## Overview Assistable's **Automatic Data Extraction** lets your AI automatically extract specific information (name, email, budget, etc.) from voice and chat conversations and sync it to GoHighLevel custom fields — with zero latency and 100% reliability. This is the **recommended approach** over using live Extraction Tools (function calling) due to superior reliability and speed. ## Prerequisites 1. **GoHighLevel sub-account** with target Custom Fields already created 2. **Assistable assistant** created and ready for configuration ## Setup 1. Go to **Settings > Custom Fields** in your GHL sub-account 2. Click **Add Field** 3. Select **Single Line Text** (string) — the most forgiving type 4. Note the exact field name (e.g., `client_budget`) 1. Open your Assistable dashboard 2. Select the assistant you're configuring 3. In the **Global Settings** menu, click **Map Custom Fields** Click **New Data Extraction** and configure: * **Name**: Clear internal name (e.g., "Customer Name") * **Type**: `string` (safest for most data — even numbers like "\$5k-10k") * **Description**: What to extract (e.g., "The caller's full name") * **Custom Field**: Map to the GHL custom field you created Save the extraction. Test with a conversation and refresh the contact record to verify fields are populated. You can create multiple extractions for different data points — name, email, budget, preferred time, etc. Each runs automatically without tool calls or added latency. ## Related Pages Alternative approach using Automatic Data Collection Flow Builder extraction nodes Save address data via custom tool Update CRM contacts # Flow Builder Guide Source: https://docs.assistable.ai/how-to-guides/flow-builder-guide Comprehensive guide to using Flow Builder for smarter AI assistants. ## Overview Flow Builder makes your AI assistants **deterministic, low-latency, and reliable**. Instead of dumping everything into one big prompt (which causes hallucinations and slow responses), Flow Builder breaks the assistant's logic into step-by-step nodes that control both conversation flow and tool usage. ## Core Principles * **Determinism** — Each step (node) has a single task; the AI cannot skip or improvise * **Minimal prompts** — Only essential instructions per step * **Tools per node** — Tools are enabled only where needed, reducing latency * **Base prompt + dynamic tasking** — Identity and personality remain constant while task instructions change per step * **Voice & Chat support** — Works seamlessly across both ## Getting Started Go to **Assistable → Add New AI Assistant → Add Flow Builder**. Give the assistant a name and identity. Set the AI's global identity and guidelines: ``` You are Haley, a polite scheduling assistant. Always stay concise, professional, and user-friendly. ``` This base prompt applies across all nodes. Add [Conversation nodes](/build/flow-builder/conversation-node) for each step of the dialogue, connected by transitions. Add [Logic nodes](/build/flow-builder/logic-node) for branching, [Extraction nodes](/build/flow-builder/extraction-variable-nodes) for data capture, and [Request nodes](/build/flow-builder/request-node) for API calls. Set up your [LLM API key](/build/flow-builder/api-key) (OpenAI, Anthropic, or OpenRouter). Use the [built-in test panel](/build/flow-builder/testing) to simulate conversations and verify behavior. Deploy as a [chat widget](/build/flow-builder/embedding-widget) or connect to [voice via Telnyx](/build/flow-builder/voice-connection). ## Node Types Reference AI dialogue and transitions Conditional branching Extract and set data External integrations Raw HTTP API calls Dynamic data system ## Related Resources * [Node Builder AI](/build/flow-builder/node-builder-ai) — Generate nodes with AI * [Engine & Streaming](/build/flow-builder/streaming) — How the engine works * [Testing](/build/flow-builder/testing) — Debug your flows # Connect AI to Google Sheets Source: https://docs.assistable.ai/how-to-guides/google-sheets Set up a knowledge base for your AI assistant using Google Sheets and Buildship. ## Overview Connect your AI assistant to **Google Sheets** via Buildship to create a real-time knowledge base. Your AI can fetch property listings, pricing data, inventory, or any structured data directly from a spreadsheet during conversations. ## Requirements * **Google Sheets** with structured data * **Buildship** account (no-code backend builder) * **Assistable** assistant for integration ## Setup Create a Google Sheet with structured data. Example columns: Date Listed, Price, Address, Zip Code, Square Footage, Bedrooms, Bathrooms. Note the **sheet tab name** (bottom left corner) — you'll need it in Buildship. 1. Log in to [Buildship](https://buildship.io) 2. Create a new workflow 3. Add the pre-built **Sheets** node → choose **Get Sheets** 4. Click **Auth** to connect your Google account 5. Configure the sheet ID and tab name 6. Deploy the workflow and copy the endpoint URL 1. In your assistant, create a new custom tool 2. Set the endpoint to your Buildship URL 3. Add parameters for any query filters (optional) 4. Save and add to your assistant Instruct the AI when to query the spreadsheet and how to present the data to users. For frequently changing data (pricing, availability), Google Sheets + Buildship is faster to update than rebuilding your knowledge base. ## Related Pages Custom tool fundamentals Optimize your AI's knowledge Fetch data from websites # Multi-Calendar Booking Source: https://docs.assistable.ai/how-to-guides/multi-calendar-booking Set up AI booking across multiple calendars using custom tools. ## Overview Enable your AI assistant to book appointments across multiple calendars. This is essential for businesses with multiple staff members, locations, or service types. ## Setup Use the built-in multi-calendar booking custom tool or create your own: 1. Create a custom tool that accepts calendar selection parameters 2. Configure the tool to route bookings to the correct calendar based on the conversation context 3. Add the tool to your assistant 4. Update your prompt to instruct the AI when to use each calendar Include a clear decision matrix in your prompt so the AI knows which calendar to use for each scenario. # No-Show Follow-Up Automation Source: https://docs.assistable.ai/how-to-guides/no-show-followup Automatically contact and reschedule clients who miss appointments using AI voice calls. ## Overview This automation detects when an appointment is marked **No Show** in GoHighLevel, triggers an AI voice call via Assistable, and attempts to reschedule the client — all without manual intervention. ## What It Does 1. **Detects** appointment marked as No Show in GHL 2. **Triggers** an automated AI voice call 3. **AI asks** for the reason and offers to reschedule 4. **Books** a new appointment if the client confirms 5. **Saves notes** summarizing the call to the contact record ## Setup 1. Go to **Assistable Dashboard → Create Assistant** 2. Name: "No-Show Follow-Up Bot" 3. Configure the prompt with a friendly, empathetic script that asks why they missed and offers to reschedule 4. Add calendar booking tools 5. Save and deploy Use **Import → Paste Bot ID** to clone a pre-built no-show assistant. Verify calendar mapping and tools migrated correctly. 1. Go to **Automation > Workflows > Create New** 2. Trigger: **Appointment Status → No Show** 3. Action: Use the Assistable API to initiate an outbound AI voice call 4. Pass the contact ID and assistant Bot ID Mark a test appointment as No Show and verify the AI calls, attempts to reschedule, and logs notes. ## Benefits * **Reduces manual workload** for staff * **Improves rebooking rates** and client retention * **Maintains high calendar utilization** * **Standardizes communication** across all follow-ups ## Related Pages Reduce no-shows with deposits Send conversation transcripts Configure voice assistants Book across multiple calendars # Send Emails from Chat Source: https://docs.assistable.ai/how-to-guides/send-emails-from-chat Enable your AI to send emails during SMS and live chat conversations. ## Overview Configure your AI assistant to send emails on request during SMS and live chat conversations. This uses a custom tool connected to a GHL workflow webhook. ## Setup In GHL, create an automation with an Inbound Webhook trigger. Add a "Send Email" action with dynamic fields mapped from the webhook data. Create a custom tool with parameters for recipient email, subject, and body. Set the endpoint to your webhook URL. Instruct the AI to use this tool when a user asks for information to be emailed. # Send SMS During Calls Source: https://docs.assistable.ai/how-to-guides/send-sms-during-calls Send links and information via text message during active phone calls. ## Overview Enable your AI voice assistant to **send SMS messages during active phone calls** — perfect for sharing links, documents, or information that can't be conveyed over voice alone. ## Setup In your assistant settings: * **Name**: `sms_content` * **Description**: "Trigger when the user requests links, resources, or information via SMS during a call. Sends the requested information instantly." * Save (endpoint URL added in the next step) 1. Go to **Automations → Create New Workflow** 2. Name: "Custom Tool - Send SMS During Call" 3. Add trigger: **Inbound Webhook** 4. Copy the webhook URL and paste it into your custom tool's endpoint field In the workflow, add an **SMS** action after the webhook trigger. Configure the message body to include the link or information passed from the AI. Add instructions and the link to your AI prompt. Tell the assistant when to offer sending a text (e.g., when sharing URLs, booking links, or documents). This is the reverse of [Call from SMS](/build/custom-tools/call-from-sms) — there you go from text to voice, here you go from voice to text. ## Related Pages Transition from SMS to phone calls Custom tool fundamentals Configure voice assistants # Transcript Workflows Source: https://docs.assistable.ai/how-to-guides/transcript-workflows Send conversation transcripts from Assistable to GoHighLevel via automated workflows. ## Overview This workflow automatically sends a formatted conversation transcript to relevant parties whenever an appointment is booked. It uses the Assistable API to fetch messages, custom code to format them, and GoHighLevel's workflow engine to deliver the result. ## Workflow Summary | Step | Action | Purpose | | ---- | ------------------------------------ | ------------------------------------- | | 1 | Trigger: Appointment Status → Booked | Start when a booking is set | | 2 | Custom Webhook (Assistable API) | Fetch conversation messages | | 3 | Custom Code | Format raw JSON into clean transcript | | 4 | Email or Notification | Deliver transcript to recipients | ## Setup Instructions Create a new GHL workflow with trigger: **Appointment Status Changed → Booked**. Configure a GET request: * **URL**: `https://api.assistable.ai/v2/get-conversation` * **Header**: `Authorization: Bearer {{Your_v2_api_key}}` * **Query Params**: `contact_id` → `{{contact.id}}`, `location_id` → `{{location.id}}` * Enable **Save Response** Map the webhook response messages to a custom code step that converts raw JSON into readable text. Use the message array from `{{custom_webhook.1.response.messages}}`. Add an **Email** or **Internal Notification** action that includes the formatted transcript output. Combine with [Send Conversation Summary](/build/custom-tools/send-summary) for a shorter summary instead of the full transcript. ## Related Pages Send summaries instead of full transcripts Extract key data from conversations Automate no-show follow-ups # Update Contact Name After Call Source: https://docs.assistable.ai/how-to-guides/update-contact-name Automatically update a contact's name from 'Guest Caller' after the AI collects it. ## Overview When incoming callers are saved as "Guest Caller," this automation prompts the AI to ask for and update the contact's real name. ## Setup Create a GHL automation with an **Inbound Webhook** trigger. Build a tool called "Contact Info Update" with `first_name` and `last_name` parameters. Set the endpoint to your webhook URL. Add instructions for the AI to ask the caller for their name and trigger the update tool. In the workflow: Find Contact by ID → Update Contact fields (first\_name, last\_name) from webhook data. # Connecting to GHL (Video) Source: https://docs.assistable.ai/integrations/ghl-connection-video Video walkthrough of connecting Assistable to GoHighLevel. ## Overview Watch the step-by-step video guide for connecting your GoHighLevel workspace to Assistable. For written instructions, see [GHL Direct Connection](/integrations/ghl-direct-connection) or [GHL OAuth](/integrations/ghl-oauth). ## Connection Methods Install Assistable as a menu item in GHL. Connect directly to a GHL sub-account. Connect external sub-accounts via OAuth. # GHL Direct Connection Source: https://docs.assistable.ai/integrations/ghl-direct-connection Connect directly to a GoHighLevel sub-account for $97 plan users. ## Overview For \$97/month GHL users who have a single sub-account, you can connect directly to Assistable without the full agency workspace setup. ## Setup Create your Assistable account. Follow the connection wizard to link your GHL sub-account directly. Ensure all required permissions are enabled, including "Allow Custom Conversation Providers." This connection method is specifically for GHL users on the \$97 plan with direct sub-account access. # GHL Custom Menu Link Source: https://docs.assistable.ai/integrations/ghl-menu-link Install Assistable as a custom menu link in your GoHighLevel workspace. ## Overview Import sub-accounts and install Assistable as a custom menu link in your GoHighLevel workspace. This gives your clients direct access to their AI dashboard from within GHL. ## Setup In your Assistable workspace, go to the integration settings. Copy the custom menu link URL provided for your workspace. In GoHighLevel, go to Settings → Custom Menu Links → Add the Assistable URL as a new menu item. Set which sub-accounts can see the menu link and configure any access restrictions. # GHL OAuth Connection Source: https://docs.assistable.ai/integrations/ghl-oauth Connect external GoHighLevel sub-accounts to your workspace via OAuth. ## Overview OAuth enables you to connect external GoHighLevel sub-accounts (those not natively under your GHL workspace) to your Assistable workspace. This is useful for agencies that manage clients across multiple GHL workspaces. ## Setup In your Assistable workspace, go to the OAuth configuration section. Create an OAuth authorization link for the external sub-account. Have the sub-account owner click the link and authorize the connection in GoHighLevel. Confirm the sub-account appears in your Assistable workspace dashboard. ## Troubleshooting See [OAuth Configuration](/troubleshooting/oauth-configuration) for common issues and solutions. # Call Tagging Source: https://docs.assistable.ai/monitor/call-tagging Automatic tags applied to contacts after AI calls for disposition tracking and workflow automation. ## Overview Whenever an AI call finishes, tags are automatically added to the contact to signify the call outcome and disposition. Use these tags to build post-call automations, campaigns, and reporting. ## Available Tags | Tag | Description | | ----------------------------- | -------------------------------------- | | `answered` | Call was answered by the contact | | `not answered` | Contact did not answer | | `ai voice appointment booked` | AI successfully booked an appointment | | `voicemail reached` | Call went to voicemail | | `contact hangup` | Contact ended the call | | `ai hangup` | AI ended the call | | `dial failed` | Call failed to connect | | `dial no answer` | Dialed but no answer received | | `call transfer` | Call was transferred to another number | | `machine detected` | Answering machine or IVR detected | | `max duration reached` | Call hit the duration limit | | `dial busy` | Line was busy | | `inactivity` | Call ended due to inactivity | | `scam detected` | Potential scam call detected | More tags are being added regularly. Check your dashboard for the latest list. ## Using Tags in Workflows Tags integrate seamlessly with GoHighLevel workflows: * **Trigger on Tag Added** to start post-call automations * Use tags **instead of or alongside** post-call webhooks * Build campaigns based on disposition (e.g., retry unanswered calls, follow up on booked appointments) # CRM Transcripts Source: https://docs.assistable.ai/monitor/crm-transcripts Automatically log AI call transcripts and summaries to your CRM contact records. ## Overview After every AI voice call, you can automatically capture and store the call transcript, summary, sentiment, and metadata in your GoHighLevel CRM. This keeps contact records up-to-date for follow-up and reporting. ## Setup See [Pre-Call & Post-Call Webhooks](/deploy/webhooks/pre-post-call) for the complete setup guide. The key steps are: 1. **Create post-call webhook workflow** in GHL 2. **Create custom fields** for Conversation Summary and AI Conversation Transcript 3. **Map webhook data** to those fields 4. **Optionally add notes** with call metadata ## Available Data The post-call webhook provides: * `call_summary` — AI-generated summary of the conversation * `full_transcript` — Complete conversation transcript * `user_sentiment` — Detected caller sentiment * `call_time_seconds` — Call duration * `recording_url` — Link to call recording * `disconnection_reason` — Why the call ended * `call_completion` — Whether the call completed successfully # DNC Compliance Source: https://docs.assistable.ai/monitor/dnc-compliance How Assistable's multi-layered Do Not Call compliance system works for outbound calls. ## Overview Assistable.ai includes a built-in, multi-layered DNC compliance system that automatically screens outbound AI calls before they are placed. ## Compliance Flow Every outbound call passes through these checks: ### 1. Lead Attribution Check The system checks if GHL knows where the lead came from: * **Known source** → DNC screening bypassed (documented relationship exists) * **Unknown source** → Full compliance flow ### 2. Internal DNC List Checks Assistable's own records: * Has this number opted out before? * Has this number been flagged in a previous check? * If YES → Call blocked ### 3. National & State DNC Registry Queries national and state-level DNC registries: * If found on any list → Call blocked * If not found → Call proceeds ## Decision Tree ``` Call Requested (GHL Workflow) │ ├─ Lead attribution known? │ ├─ YES → Call proceeds (bypass DNC) │ └─ NO → Enter compliance flow │ │ │ ├─ On internal DNC list? │ │ ├─ YES → Call BLOCKED │ │ └─ NO → Continue │ │ │ └─ On national/state DNC registry? │ ├─ YES → Call BLOCKED │ └─ NO → Call proceeds ``` ## Bypass Options ### Option 1: Opt Out Entirely Disable all DNC screening for your account. Common in REI and cold outreach industries. Opting out means your organization assumes full legal responsibility for all DNC violations, including FTC/FCC fines and TCPA lawsuits (up to \$51,744 per call). ### Option 2: Import Number Bypass Bypass DNC only for specific imported numbers: 1. Import your phone numbers 2. Go to Account Settings 3. Enable DNC opt-out for imported numbers ## Monitoring Blocked Calls In your GHL workflow: 1. After the **Make AI Call** action, add an **If/Else** branch 2. Condition: `Make AI Call action return_an_error = true` 3. If true → Send notification with `error_message` variable ## Comparison with GHL Native Calling | Feature | GHL Native | Assistable | | ----------------------- | ---------------- | ------------------------------------------- | | Non-opted-in leads | Blocked entirely | Allowed with compliance checks | | Lead attribution bypass | Not available | Known sources bypass DNC | | DNC screening | Blanket block | Multi-layered (internal + national + state) | | Bypass options | None | Full opt-out or per-import bypass | | Error visibility | Limited | Full error messages in workflows | ## Best Practices * Keep lead attribution clean — properly tag lead sources * Always set up error monitoring after Make AI Call actions * Use import bypass sparingly and only for vetted lists * Consult legal counsel before opting out of DNC screening * Review blocked call reports regularly # AI Call Error Tags Source: https://docs.assistable.ai/monitor/error-tags Automatic error tags applied when the Make AI Call action encounters issues. ## Overview When the Make AI Call action encounters an error, Assistable automatically applies an error tag to the contact. These tags identify exactly what went wrong — rate limits, DNC hits, billing issues, or other failures. In addition to tags, two custom fields are populated: `Make AI Call returned_an_error` (boolean) and `error_message` (human-readable description). ## Error Tags Reference | Tag | Description | | ------------------------------------------ | ------------------------------------------------------------------------ | | `ai_call_error_rate_limit` | Account hit concurrency or per-minute call limit. Retry after a delay. | | `ai_call_error_internal_dnc` | Number on internal Do Not Call list. Call blocked. | | `ai_call_error_national_dnc` | Number on national DNC registry. Call blocked for TCPA compliance. | | `ai_call_error_workspace_negative_balance` | Workspace wallet balance insufficient. All sub-accounts affected. | | `ai_call_error_account_negative_balance` | Sub-account wallet insufficient. Top up to resume. | | `ai_call_error_workspace_inactive` | Workspace subscription cancelled or limit set to 0. | | `ai_call_error_no_from_number` | No phone number assigned to the assistant. | | `ai_call_error_invalid_destination` | Attempting to call a non-US/Canadian destination with a platform number. | | `ai_call_error_invalid_assistant` | Assistant ID doesn't belong to this sub-account. | | `ai_call_error_dnd` | Contact has Do Not Disturb enabled for calling in GHL. | | `ai_call_error_unknown` | Unexpected error. Check logs or contact support. | | `ai_call_error_invalid_number_pool` | Number pool configured but contains no numbers. | | `ai_call_error_banned` | Sub-account banned due to honeypot hits or non-compliant activity. | ## Using Error Tags in Workflows ### Basic Pattern 1. Create a workflow with **Tag Added** trigger 2. Select the specific error tag (e.g., `ai_call_error_rate_limit`) 3. Add your response actions (retry, notify, re-route) ### Common Automations * **Rate limit retry**: Wait 5 min → Remove tag → Re-run Make AI Call * **Balance alerts**: Send notification to admin to top up funds * **DNC handling**: Move contact to email-only or SMS-only campaign * **Catch-all monitoring**: Send alert to team for manual review * **Ban notification**: Pause all calling campaigns immediately Always remove the error tag after handling it if you plan to retry — otherwise the tag-added trigger won't fire again for the same tag. ## DNC Bypass Tag Coming Soon — scheduled for release March 2, 2026. A special tag `i_agree_responsibility_for_dnc_bypass` will bypass DNC screening for specific contacts. When present, Make AI Call skips both internal and national DNC checks. **⚠️ Legal Liability:** Applying this tag means the sub-account owner assumes COMPLETE LIABILITY for all TCPA lawsuits, fines, or fees. Consult a TCPA attorney before using at scale. # Number Intelligence Source: https://docs.assistable.ai/monitor/number-intelligence Monitor and analyze phone number health and performance metrics. ## Overview Number Intelligence provides a high-level view of your phone numbers with monitoring and sorting capabilities. This feature helps you: * Track phone number health * Monitor call success rates * Identify numbers that may need attention * Sort and filter your number inventory ## Usage Number Intelligence data is updated **once per month**. Navigate to the Number Intelligence section in your dashboard to view metrics and sort your numbers. This feature is continuously being enhanced with additional metrics and more frequent updates. # Agency Wallet Source: https://docs.assistable.ai/platform/agency-wallet Set up and manage your agency wallet for AI voice and messaging usage. ## Overview Your Agency Wallet is a prepaid balance that covers usage-based costs across all your sub-accounts — voice calls, messages, and other billable AI operations. **Critical**: If your agency wallet balance goes negative, **none of your sub-accounts** will be able to use inbound or outbound AI voice calling. Keep it funded! ## Setting Up Your Wallet Go to **Settings > Billing** in your workspace. Click **Add Balance** and enter the amount you want to fund. Funds are available immediately. Turn on auto-pay to automatically refill your wallet when the balance drops below a threshold. This is **strongly recommended** to prevent service interruptions. ## How It Works * Usage charges (voice minutes, messages) are deducted from your agency wallet in real time * If [rebilling](/platform/rebilling) is enabled, your clients' wallets are charged at your set rates — and the base cost is deducted from your agency wallet * You can monitor all transactions in the [Billing Portal](/platform/billing-portal) Set your auto-pay threshold higher than your typical daily usage to avoid any gaps in service. ## Related Pages Client wallet setup View transactions and invoices Set up automated client billing # Billing Portal Source: https://docs.assistable.ai/platform/billing-portal Navigate and manage subscriptions, usage billing, wallet balance, and transaction history. ## Overview The Billing Portal gives you full visibility into your workspace's financial operations — subscriptions, wallet balance, usage charges, transaction history, and invoices. ## Accessing the Billing Portal Go to **Settings > Billing** in your workspace. You'll see: * Card on file and auto-pay toggle * Current subscription details * Wallet balance * Full transaction history ## Subscription vs. Wallet | Type | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Subscription** | Monthly recurring charge for platform access plus add-ons (phone numbers, voice features) | | **Wallet** | Prepaid balance for usage-based billing (calls, messages). Usage is deducted here, not charged to your card each time. | ## Managing Your Billing Click **Update Card Info** to change the card used for wallet refills and subscription payments. Click **Enable Auto-Pay** so your wallet refills automatically when it drops below a threshold. This prevents service interruptions during high-usage periods. If auto-pay is off, click **Add Balance** to fund the wallet. Funds are immediately available. Transactions are categorized as: * **Credit** — Funds added (manual or auto-pay) * **Debit** — Usage deductions (e.g., \$0.05 per message) For credit transactions, click **Download Invoice** to get a PDF with full metadata (Stripe ID, reference info). Each debit includes an event link. Click it to open the original event (call, message) and verify the charge. ## FAQs Subscription = platform access + add-ons. Wallet = pay-as-you-go usage charges. Those are usage debits from your wallet, not your card. Your card is only charged when adding balance. Enable auto-pay to automatically refill below a set threshold. ## Related Pages Set up client billing Fund your agency wallet Connect or reset Stripe # Branding Source: https://docs.assistable.ai/platform/branding Update your workspace branding including logos, colors, and visual identity. ## Overview The Branding settings in your workspace let you customize the visual identity of your AI portal. Changes apply globally across your workspace and all sub-accounts. ## What You Can Update * **Logo** — Displayed in the portal header and sidebar * **Primary Brand Color** — Applied to buttons, links, headers, and UI accents * **Favicon** — Browser tab icon (configured in [White Labeling](/platform/white-labeling)) * **Page Title** — Browser tab text ## How to Update Branding Go to your workspace dashboard and click the **Branding** tab. Click the logo area and upload your new image. Any format (PNG, JPEG, GIF) and any size accepted. The logo updates dynamically across the entire portal. Use the color picker to select your primary brand color. This color appears on buttons, highlights, and navigation elements throughout the portal. Click **Update Branding** to apply. Changes take effect immediately across all sub-accounts. For full white-label customization including custom domains and documentation links, see [White Labeling](/platform/white-labeling). ## Related Pages Full white-label setup with custom domain Complete workspace configuration # Permissions Source: https://docs.assistable.ai/platform/permissions Control which navigation tabs and features are visible to sub-account users. ## Overview Permissions let you control which tabs and features are visible to non-admin users in a sub-account. This is useful for hiding advanced features from clients who don't need them, or for creating tiered access based on plans. ## How Permissions Work * **Admins** always see everything — permission changes only affect non-admin users * Permissions control **tab visibility** in the sub-account navigation * Changes can be set per sub-account or applied as defaults via [Snapshots](/platform/snapshots) ## Configuring Permissions Navigate to the sub-account in your workspace. Click the **Permissions** option for that sub-account. * **Check** tabs to make them visible to non-admin users * **Uncheck** tabs to hide them Apply changes. They take effect immediately for the sub-account's non-admin users. Set default permissions in your [Agency Snapshot](/platform/snapshots) so new sub-accounts are configured automatically. ## Related Pages Full management guide Restrict entire sub-account access Default permissions for new accounts Set usage limits # Rebilling Source: https://docs.assistable.ai/platform/rebilling Set up automated rebilling to charge your clients for AI usage through your workspace. ## Overview Rebilling allows you to charge your clients for AI voice minutes and other usage directly through Assistable. You set your own markup prices, and the system handles billing automatically via Stripe. ## How Rebilling Works 1. **You pay Assistable** at base rates (e.g., \$0.07/minute for voice) 2. **You set your price** for clients (e.g., \$0.10/minute) 3. **Clients fund their wallet** via their billing portal 4. **Usage is billed** from the client's wallet at your set rate 5. **You keep the margin** — the difference between your cost and the client's rate ## Setup Go to the **Rebilling** tab and click **Connect to Stripe**. Complete the Stripe OAuth flow. See [Stripe Integration](/platform/stripe-integration) for details. Configure your per-minute rate for voice calls and any other billable items. Keep your cost in mind when setting margins. Rebilling can be enabled per sub-account or set as a default for all new accounts via [Snapshots](/platform/snapshots). Clients must be [invited as members](/platform/user-management) to access their billing settings and set up their wallet. See [Subaccount Wallet](/platform/subaccount-wallet). If your agency wallet balance goes negative, **all sub-accounts lose access** to inbound and outbound AI voice calling. Keep your [Agency Wallet](/platform/agency-wallet) funded. ## Related Pages Connect or reset Stripe Fund your agency wallet Client wallet setup Understand billing and invoices Auto-configure rebilling for new accounts # Restrictions Source: https://docs.assistable.ai/platform/restrictions Restrict sub-account access with admin locks and account freezing. ## Overview Restrictions let you lock down or freeze a sub-account entirely. When restricted, the sub-account cannot be accessed without an admin password. This is useful for non-paying clients, security incidents, or accounts under review. ## How to Restrict a Sub-Account Navigate to the sub-account in your workspace's **Manage Accounts** section. Click the **Lock** option and set an admin password. The sub-account is now inaccessible without the correct password — even inspecting the page source won't reveal content. Visit the restricted account and enter the admin password to restore access. Admin locks can also be set automatically for new sub-accounts via [Snapshots](/platform/snapshots). ## Use Cases * **Non-payment** — Lock accounts until billing is resolved * **Security** — Freeze compromised accounts immediately * **Onboarding** — Lock accounts until setup is complete * **Demo accounts** — Restrict access after trial period ## Related Pages Full management guide Control feature visibility Auto-configure locks for new accounts # Snapshots Source: https://docs.assistable.ai/platform/snapshots Set up agency snapshots to automatically configure new sub-accounts with default settings. ## Overview Agency Snapshots let you define a template that's automatically applied to every new sub-account. This includes feature access, usage limits, rebilling settings, and even pre-built AI assistants — ensuring consistent onboarding and saving hours of manual setup. ## What Snapshots Configure * **Feature access** — Toggle which features new sub-accounts can see * **Usage limits** — Max assistants, messages, phone numbers * **Rebilling** — Auto-enable rebilling with preset voice minute pricing * **Assistant templates** — Clone pre-built assistants into new accounts * **Admin lock** — Optionally lock new accounts with a password ## Setting Up a Snapshot Click the **Agency** tab in your main dashboard. Under **New Accounts Have a Snapshot**, toggle ON features you want new sub-accounts to have. Toggle OFF features you want to hide from clients (admins still see everything). Define limits for max assistants, max messages, etc. — or leave them as unlimited. Turn on rebilling and set your per-minute rate (e.g., $0.10/minute when your cost is $0.07). 1. Go to a sub-account with a well-built assistant 2. Copy its **Assistant Snapshot ID** 3. Return to agency settings and paste it into the **Assistant Snapshot** field 4. Click **Add** — this assistant will auto-clone into all new sub-accounts Set an admin password to lock new sub-accounts. The account is inaccessible without the correct password — even inspecting the page source won't expose content. ## Testing Your Snapshot Create a new sub-account to verify: * Rebilling prompt appears (if enabled) * Pre-selected features are enabled/hidden correctly * Pre-added assistants are visible and ready to use * Admin lock works as expected ## FAQs No. Admins always see everything. Hiding only affects client visibility. Yes. Changes apply to new accounts going forward (existing accounts are not affected). Yes. Once added via snapshot ID, the assistant is cloned into every new sub-account automatically. ## Related Pages Manage existing sub-accounts Configure client billing Control feature visibility Complete workspace configuration # Stripe Integration Source: https://docs.assistable.ai/platform/stripe-integration Connect or reset your Stripe integration for rebilling setup. ## Overview Stripe integration is required for [Rebilling](/platform/rebilling). It allows your workspace to collect payments from clients through their wallet and process billing automatically. ## Connecting Stripe Go to the **Rebilling** tab in your workspace navigation. A Stripe OAuth modal opens in a new window. Choose the appropriate Stripe account and click **Connect**. Stripe redirects you back to your workspace. You'll see the active Stripe connection displayed under the Rebilling tab. ## Resetting the Connection If you need to switch Stripe accounts or troubleshoot: Go to the **Rebilling** tab (or **Integrations** tab) and click **Break Connection**. Breaking the connection does **not** affect previously saved billing data. Click **Connect to Stripe** again and follow the OAuth flow with your new account. ## FAQs No — it only resets the Stripe connection. All billing history remains intact. Yes, both tabs provide the same connection process. Check your browser's pop-up blocker or try in a different browser. ## Related Pages Set up automated client billing Manage subscriptions and wallet Fund your agency wallet # Sub-Account Management Source: https://docs.assistable.ai/platform/sub-account-management Manage sub-accounts within your workspace — edit info, set limits, control permissions, and more. ## Overview After sub-accounts are synced to your workspace, you can manage every aspect of them from the Agency Dashboard — edit account details, set usage limits, control feature visibility, invite users, and handle billing. ## Managing a Sub-Account In your workspace, locate and click the desired sub-account. You can **pin favorites** to keep frequently-accessed accounts at the top. Click **Edit Account** to modify: * Sub-account name, email, phone number * Website and time zone Info is auto-filled from GoHighLevel via OAuth but can be changed manually. Click **Save Changes** to confirm. Go to **Manage Limits** to define: * Maximum number of assistants * Maximum messages * Phone number limits Set specific limits or make everything unlimited. See [Subaccount Limits](/platform/subaccount-limits) for details. Use **Permissions** to control which tabs are visible to non-admin users. Admins always see everything. See [Permissions](/platform/permissions). Click **Invite Member** to add users by email. New users are created automatically. Members need access to see the billing tab and manage settings. See [User Management](/platform/user-management). Use **Lock/Unlock** for admin-level security. Requires an admin password. Useful for restricting or freezing access temporarily. If sync breaks, use **Agency Connection** to refresh or **Direct Connect** to manually re-authenticate. Set up per-account [rebilling](/platform/rebilling) rates for voice minutes and other usage. ## Related Pages Configure usage limits Control feature visibility Restrict sub-account access Add and remove users Set up client billing Full workspace configuration # Subaccount Limits Source: https://docs.assistable.ai/platform/subaccount-limits Set and manage usage limits for individual sub-accounts. ## Overview Subaccount limits let you control how much each sub-account can use — including the number of assistants, messages, phone numbers, and other resources. This is useful for managing plan tiers, preventing overuse, or restricting demo accounts. ## Configuring Limits In your workspace, find the sub-account you want to configure. Open the limits panel for that sub-account. Configure maximum values for: * **Max Assistants** — How many AI assistants the account can create * **Max Messages** — Total message volume * **Phone Numbers** — Number of phone numbers allowed * Any other billable resources You can set specific numeric limits or mark each as **unlimited**. Click save to apply. Limits take effect immediately. Use limits in combination with [Snapshots](/platform/snapshots) to automatically set default limits for new sub-accounts based on their plan tier. ## Related Pages Full management guide Auto-configure limits for new accounts Control feature visibility Restrict sub-account access # Provisioning API Source: https://docs.assistable.ai/platform/subaccount-provisioning-api Create a GoHighLevel sub-account from a Location ID over the API — no per-location manual OAuth. ## Overview Once your agency has completed the **agency-level GoHighLevel OAuth** (installing the Assistable marketplace app), you can provision a sub-account for any Location your agency has installed — directly over the API, with no per-location manual OAuth step. This is the automation path for onboarding many clients at once. The agency OAuth install is the only prerequisite. Assistable mints a location-level token from your agency install on demand, so individual Locations do **not** each need to authorize separately. ## Provision from a Location ID `POST /v3/subaccounts` with a `location_id` creates a GoHighLevel-connected sub-account for that Location and hydrates its details (name, address, timezone, contact info) from GoHighLevel. Needs a key with the `subaccounts:create` scope. ```bash theme={null} curl https://api.assistable.ai/v3/subaccounts \ -H "Authorization: Bearer ask_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "location_id": "ve9EPM428h8vShlRW1KT" }' ``` ```json theme={null} { "data": { "id": "sub_123", "name": "Acme HVAC", "integrationType": "GO_HIGH_LEVEL", "integrationId": null, "locationId": "ve9EPM428h8vShlRW1KT", "webhookUrl": null, "webhookSecret": null, "createdAt": "2026-07-01T00:00:00.000Z" }, "error": null, "request_id": "req_…" } ``` `POST /v3/subaccounts` takes **exactly one** of `location_id` (provision from GoHighLevel, shown here) or `name` (create a native [Assistable Direct](/direct/provisioning) sub-account). Supplying both — or neither — returns `400 validation_error`. ## Ownership & idempotency * **Agency ownership is enforced.** Assistable provisions a Location only if it is installed under *your* agency. A Location that isn't returns `404 location_not_found`. * **Idempotent per Location.** Re-calling with a `location_id` your workspace has already provisioned returns the existing sub-account (`200`) instead of creating a duplicate — safe to retry. * A Location already provisioned in **another** workspace returns `409 location_conflict`. ## Errors | Status | Code | Meaning | | ------ | -------------------- | ---------------------------------------------------------------------------------------------- | | `409` | `ghl_not_connected` | The key's workspace hasn't completed GoHighLevel agency OAuth. Connect the agency, then retry. | | `404` | `location_not_found` | That Location isn't installed under your agency. | | `409` | `location_conflict` | The Location is already provisioned in another workspace. | | `403` | `forbidden` | The API key is missing the `subaccounts:create` scope. | ## Related Pages Manage provisioned sub-accounts Create native (GHL-free) sub-accounts # Subaccount Wallet Source: https://docs.assistable.ai/platform/subaccount-wallet Set up wallets for your sub-accounts so clients can fund their AI usage. ## Overview Each sub-account has its own wallet that funds their AI usage (voice calls, messages). Clients add funds to their wallet, and usage is billed at the rates you set via [Rebilling](/platform/rebilling). ## Prerequisites Before a client can set up their wallet, they must be **invited as a member** to their sub-account. Without this, they won't see the billing settings. **Why can't my client see their billing settings?** They need to be invited as a workspace member first. Go to your Agency Dashboard, find their sub-account, click **Invite Member**, and send an invite to their email. Once accepted, they'll see the Billing menu and can set up their wallet. ## Client Wallet Setup Once invited as a member, your client can: 1. Navigate to their sub-account's **Settings > Billing** 2. Add a payment card 3. Fund their wallet 4. Enable auto-pay for automatic refills ## How Usage Is Billed * Usage charges are deducted from the sub-account's wallet at the rates you configured * If the wallet runs dry, AI services pause until funds are added * Transaction history is visible to the client in their billing portal If you want another user to access billing settings, they also need to be [added as a member](/platform/user-management) of the workspace. ## Related Pages Your agency-level wallet Set client pricing Invite members to sub-accounts Understand billing and invoices # User Management Source: https://docs.assistable.ai/platform/user-management Add and remove users in your workspace and sub-accounts. ## Overview User management lets you invite team members, clients, and third-party professionals to your workspace or individual sub-accounts. Users need to be members to access billing settings, manage assistants, and configure their accounts. ## Adding Users to Your Workspace Go to **Settings > Members** in your workspace. You can also use the Launchpad's "Add Team Member" shortcut. 1. Click **Invite Member** 2. Enter the user's email address 3. Click **Send Invite** If the email isn't associated with a GoHighLevel account, one is created automatically and a password reset link is sent. In **Settings > Members**, find the user and click the **trash icon**. Access is revoked instantly. ## Adding Members to Sub-Accounts To give a client access to their sub-account (including billing): 1. Go to your Agency Dashboard 2. Find the client's sub-account 3. Click **Invite Member** 4. Enter their email and send the invite Clients **must** be invited as members before they can see their Billing settings or set up their [wallet](/platform/subaccount-wallet). ## FAQs One is created automatically. They'll receive a password reset email. No, but their access is revoked instantly. No — each user must be invited individually by email. Yes, but they must first be added as a member of the workspace. ## Related Pages Full sub-account management guide Client wallet setup Control feature visibility Restrict sub-account access # White Labeling Source: https://docs.assistable.ai/platform/white-labeling White label your Assistable portal with custom branding, domain, and documentation. ## Overview White labeling lets you rebrand the entire Assistable portal as your own product. Upload your logo, customize colors, set a custom domain, and even embed your own documentation — your clients never see the Assistable brand. ## What You Can Customize | Element | Description | | --------------------- | ------------------------------------------------------------------- | | **Logo** | Your company logo displayed across the portal | | **Brand Colors** | Primary color applied globally to buttons, headers, and UI elements | | **Custom Domain** | Your own domain (e.g., `ai.youragency.com`) instead of Assistable's | | **Favicon** | Browser tab icon for your white-labeled portal | | **Page Title** | Custom browser tab title | | **iFrame Embed** | Embed landing pages or custom content | | **Documentation URL** | Link to your own docs, shown as a "Docs" button in sub-accounts | ## Setup Steps Navigate to the **Branding** tab in your workspace. Click the logo upload area and upload your image (PNG, JPEG, or GIF — any size works, square recommended). Choose your primary brand color using the color picker. Click **Update Branding** to apply it globally across your workspace and all sub-accounts. 1. In the **Branding** tab, scroll to the **Domain** section 2. Enter your custom domain (e.g., `ai.youragency.com`) 3. In your DNS provider, add an **A Record** pointing to `72.72.71.71` 4. Wait for DNS propagation and confirm the domain is connected 5. Set your favicon and page title Paste your documentation page URL in the branding settings. Sub-accounts will see a "Docs" button linking to your docs. ## FAQs PNG, JPEG, and GIF — any image format and size. Yes, use the iFrame embed option to display landing pages within the portal. Only if you provide a URL — then it appears in all sub-account views. ## Related Pages Update logos and colors Complete workspace configuration Manage client accounts # Workspace Setup Source: https://docs.assistable.ai/platform/workspace-setup Set up and configure your Assistable workspace for managing AI assistants at scale. ## Overview Your workspace is the top-level container for all your AI operations in Assistable. From the **Agency Dashboard**, you manage sub-accounts, billing, branding, user access, and more. This guide covers the essential steps to get your workspace fully configured. ## What You Can Do From the Agency Dashboard Brand your portal with custom domain and logo Create and manage client sub-accounts Set up automated client billing Template new sub-accounts automatically Add team members and client users Manage subscriptions and wallet ## Getting Started Link your GHL workspace to Assistable via OAuth or direct connection. See [Getting Started](/getting-started) for detailed instructions. Click **Import Installed** to fetch all sub-accounts linked to your GHL connection. Select specific accounts or import all at once. If you're on a limited plan, avoid importing more than your plan allows — archive extras as needed. Copy your unique **Custom Menu Link** from the workspace and add it in GoHighLevel under **Settings > Custom Menu**. This embeds your AI Portal into every sub-account's sidebar. Upload your logo, set brand colors, and configure your [white-label domain](/platform/white-labeling) so everything looks like your brand. Connect [Stripe](/platform/stripe-integration) for rebilling, configure your [agency wallet](/platform/agency-wallet), and set pricing for voice minutes. Set up a [snapshot](/platform/snapshots) to automatically configure new sub-accounts with default features, assistants, and billing settings. ## Custom Menu Link Details The custom menu link makes your AI Portal appear as a sidebar item in every GoHighLevel sub-account: 1. In your workspace, click **Custom Menu Link** and copy the URL 2. In GoHighLevel Agency View, go to **Settings > Custom Menu > Create** 3. Paste the URL (leave variables untouched — they auto-configure per sub-account) 4. Set it as an iframe, name it (e.g., "AI Portal"), and enable for all sub-accounts 5. **Enable microphone access** for voice testing via the embedded Voice Lab New sub-accounts automatically sync via OAuth and display the AI Portal based on your custom menu link configuration. ## Related Pages Update logos and colors Control sub-account navigation visibility Restrict sub-account access Set usage limits per sub-account # Calendar Debugging Source: https://docs.assistable.ai/troubleshooting/calendar-debugging Troubleshoot calendar booking issues with your AI assistant. ## Common Calendar Issues ### Calendar Not Synced * Go to Calendar settings and verify the correct calendar is selected * Re-sync the connection if needed * Test by running a calendar availability check ### Wrong Availability Showing * Check calendar permissions * Verify timezone settings match between your calendar and the assistant * Ensure no conflicts with other calendar tools ### Bookings Not Appearing * Confirm all calendar tools are enabled (Check Availability, Book, Reschedule, Cancel) * Test each tool individually * Check the calendar for permission restrictions # Chat Response Optimization Source: https://docs.assistable.ai/troubleshooting/chat-response-optimization Optimize AI response time and queuing settings for faster, more natural chat interactions. ## Overview This guide covers configuring and optimizing AI response times and queuing settings to balance speed, accuracy, and a natural conversational feel. ## Steps to Optimize Create a new assistant and add an **Active Tag** to enable logging and monitoring. In the assistant's settings, locate **Wait Time** and adjust: * **Zero seconds** — Instant responses, ideal for widgets or fast interactions * **15+ seconds** — More human-like delays for conversational realism * **Minimize prompt length** to reduce processing time * **Avoid verbose instructions** — focus on concise, direct commands * Use **templates or structured prompts** for clarity without bulk Analyze logs to identify the impact of: * Tool calls integrated within the assistant * Conversation history size (larger contexts slow processing) Remove or simplify unnecessary tools and context. For non-immediate workflows, add 5-10 second delays to allow time for workflow detection or tag processing. Connect relevant [knowledge bases](/troubleshooting/knowledge-base-optimization) — but ensure they're focused and not overly broad. Simulate varied scenarios: * Simple inquiries vs. complex requests * High vs. low context demands * Record response time metrics ## Key Factors Affecting Response Time | Factor | Impact | Recommendation | | ------------------------ | ---------------------------- | --------------------------- | | **Prompt length** | Longer = slower | Keep concise | | **Number of tools** | More tools = more processing | Only enable needed tools | | **Conversation history** | Larger context = slower | Keep conversations focused | | **Knowledge base size** | Larger = slower embedding | Use targeted FAQ entries | | **Model choice** | Larger models are slower | Use `gpt-4o-mini` for speed | ## Related Pages Build a better knowledge base How the Flow Builder engine works Choose the right model # Common Issues & Solutions Source: https://docs.assistable.ai/troubleshooting/common-issues Quick fixes for the most frequently encountered problems. ## Common Issues ### AI Not Making Calls 1. **Check wallet balance** — Agency wallet and sub-account wallet must have positive balances 2. **Check phone number** — Assistant must have a number assigned 3. **Check DNC** — The number may be on a Do Not Call list 4. **Check assistant ID** — Verify the correct assistant ID in your workflow ### AI Not Responding to Chat 1. **Check Active Tags** — Contact must have an active tag assigned 2. **Check `ai_off` tag** — Remove it if present 3. **Check Sleep Mode** — AI may be paused after an outbound message ### Calls Going to Voicemail * Enable voicemail detection in call settings * Consider adjusting call timing for better pickup rates ### Calendar Not Booking * See [Calendar Debugging Guide](/troubleshooting/calendar-debugging) * Verify calendar sync and permissions ### Webhook Not Firing * Verify the webhook URL is correct and confirmed (green checkmark) * Check that the workflow is published * Try fetching a sample request to verify connectivity # Dial Failed Errors Source: https://docs.assistable.ai/troubleshooting/dial-failed Resolve 'Dial Failed' errors on AI outbound calls. ## Overview The "Dial Failed" error occurs when an outbound call cannot be connected. This is most commonly a SIP trunking configuration issue. ## Common Causes ### Twilio * **IP Access Control Lists not configured** — You must add both ACL entries (0.0.0.0/1 and 128.0.0.0/1) * **Origination URI missing** — Inbound calls require the origination URI to be set * **Termination URI incorrect** — Double-check the URI in your Assistable import settings * **Account not verified** — Twilio requires account verification before making calls ### Telnyx * **FQDN not configured** — Must be set to `5t4n6j0wnrl.sip.livekit.cloud` * **Wrong inbound format** — Must be +E.164 format * **Missing outbound voice profile** — Create and select one ### General * **Number format** — Must be raw E.164 format (+1XXXXXXXXXX) * **International restrictions** — Platform numbers only support US/Canadian (+1) destinations * **Wallet balance** — Check both agency and sub-account wallets * **Number not assigned** — Verify the assistant has a phone number linked Assistable stores the SIP info you provide. Whether calls connect depends on your telephony provider's configuration. For persistent issues, contact your provider's support. # Knowledge Base Optimization Source: https://docs.assistable.ai/troubleshooting/knowledge-base-optimization Build and optimize a knowledge base for accurate, reliable AI assistant responses. ## Overview A well-built knowledge base is critical for accurate, domain-specific AI responses. The knowledge base provides context on a per-interaction basis — the system compares the contact's message against your knowledge base to generate specific, relevant answers. The AI doesn't "know" your knowledge base — it uses it as **contextual input** to generate responses. The quality of output is directly tied to the quality of input. ## Key Concepts * **Knowledge as context** — Information is injected per interaction, not memorized * **Best content types** — FAQ pairs, objection handling, cause-effect relationships * **Quality in = quality out** — Poor or unclear data leads to poor responses ## Best Practices ### Preferred Input Types 1. **FAQ format** — Precise Q\&A pairs deliver the most reliable results 2. **Raw text** — Sourced from your website, documentation, or transcripts 3. **Document uploads & website scrapes** — Useful but may introduce conflicting information Source raw text from your website, YouTube transcripts, or documentation. Use ChatGPT or Claude to generate FAQs from this material — tailored for sales, support, or in different languages. ### Optimization Tips * **Use FAQ format** for common questions — best accuracy * **Keep entries focused** — One topic per entry * **Update regularly** — Outdated info causes wrong responses * **Test thoroughly** — Ask the AI questions requiring knowledge base data and verify * **Use specific language** — Be precise about services, pricing, policies * **Organize by category** — Group related entries * **Set temperature low** (0–0.2) for businesses needing precise, deterministic answers ## Monitoring Your Knowledge Base In conversation logs, click the **`{ }`** bracket icon to open transparency logs. Look for: * **"Embedding"** — The knowledge base was queried * **"Embed complete"** — Open this to see exactly what content was returned for the contact's message If the returned content isn't ideal, go back to your knowledge base and add a targeted FAQ for that question. ## Architecture: Where Things Go | Component | Purpose | | ------------------ | ------------------------------------------------------------------- | | **Prompt** | Personality, response guidelines, style guardrails, instruction set | | **Knowledge Base** | Domain-specific knowledge, FAQs, objection handling, pricing | | **Tools** | Context injection, conditional logic, data retrieval, actions | ### What About Live Data or Complex Pricing? Use [custom tool calls](/build/custom-tools/overview) to fetch live data or integrate with third-party services for complex quoting and pricing operations. ## Related Pages Optimize response times Extract user information Use spreadsheets as a knowledge source Extend AI with custom tools # OAuth Configuration Source: https://docs.assistable.ai/troubleshooting/oauth-configuration Troubleshoot OAuth connection issues between Assistable and GoHighLevel. ## Overview OAuth connects your GoHighLevel workspace or sub-accounts to Assistable. If the connection fails, follow these troubleshooting steps. ## Common Issues ### Connection Not Establishing * Verify your GHL marketplace app credentials * Check that the redirect URL is correctly configured * Ensure all required permissions/scopes are enabled ### Connection Lost * Re-authorize the connection from your GHL workspace * Check if your GHL subscription is active * Verify the OAuth token hasn't expired ### Permission Errors * Review the scopes requested during OAuth setup * Ensure "Allow Custom Conversation Providers" is enabled in GHL settings # Authentication Source: https://docs.assistable.ai/v3/authentication Bearer API keys, scopes, and selecting a subaccount. ## API keys Authenticate every request with a Bearer token: ```bash theme={null} Authorization: Bearer ask_live_xxxxxxxxxxxxxxxxxxxx ``` Keys are environment-prefixed: | Prefix | Environment | | -------------- | ----------- | | `ask_live_` | Production | | `ask_test_` | Test | | `ask_staging_` | Staging | | `ask_dev_` | Development | The full secret is shown **once** at creation. Only a prefix (`ask_live_…`) and the last 4 characters are stored for display; the key itself is stored as a SHA-256 hash. Treat keys like passwords. If a key leaks, rotate it from **Settings → API Keys** — rotation issues a new secret and invalidates the old one immediately. ## Scopes Each key carries `resource:action` scopes (e.g. `assistants:read`, `calls:create`). A request to an endpoint you lack the scope for returns `403`. Role presets: * **read\_only** → `read` + `list` on every resource * **read\_write** → full CRUD + `list` * **admin** → all scopes * **custom** → exactly the scopes you assign ## Selecting a subaccount A key may be authorized for one or more subaccounts. Tell the API which one a request targets, in priority order: 1. `X-Subaccount-Id` header (recommended) 2. `subaccount_id` in the request body 3. `location_id` in the request body (legacy alias) A single-subaccount key defaults to its one subaccount. Requesting a subaccount the key isn't authorized for returns `403`. ## IP allowlisting A key can be restricted to specific source IPs or CIDR ranges. Requests from other addresses are rejected with `401`. # How Billing Works on Assistable Source: https://docs.assistable.ai/v3/billing-guide Complete guide to Assistable's pricing model, transaction breakdowns, and agency rebilling mechanics. ## The Big Picture Think of Assistable like an arcade: * **Your wallet is your stack of arcade tokens.** Every time your AI does work (talks on a call, answers a chat, looks something up), a few tokens come out of your wallet. * **You can see every token spent.** Every charge creates a receipt (we call it a *transaction*) with a line-by-line breakdown. No mystery charges. * **Autopay keeps you playing.** When your wallet runs low, autopay tops it back up from your card automatically (you choose the amount). There are **two kinds of wallets**, because there are two kinds of customers: | Wallet | Who pays into it | What it pays for | | ---------------------- | -------------------------------- | -------------------------------------------------------------- | | **Workspace wallet** | You (the agency / account owner) | What **Assistable charges you**: our platform costs | | **Sub-account wallet** | Your client | What **you charge your client** (this is called **rebilling**) | If you don't have clients (you just use Assistable yourself), you only care about the workspace wallet. If you're an agency reselling AI to clients, both matter. ## What Assistable Charges You These come out of your **workspace wallet**. ### AI Voice Calls: billed per minute, to the second A voice call is like a taxi ride: the meter runs only while the call is happening, and you pay for *exactly* how long it ran (a 52-second call bills as 0.866 minutes, not a full minute). Each minute has a few ingredients: | Ingredient | What it is | Price | | ------------------------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------- | | **Voice engine** | The "ears and mouth": turning speech to text and text to speech | **\$0.07 / min** | | **LLM (the brain)** | The AI model doing the thinking. Price depends on which model your assistant uses | **$0.02 to $0.05 / min** (see pricing page for your model) | | **Telephony** | The phone line itself | **\$0.015 / min** | | **Short-call surcharge** | A flat fee for calls under 10 seconds (hang-ups still cost us money to connect) | **\$0.015 flat** | **Example: a 2-minute call** with a model that costs \$0.02/min: ``` Voice engine: $0.07 × 2 min = $0.14 LLM: $0.02 × 2 min = $0.04 Telephony: $0.015 × 2 min = $0.03 ───────────────────────────────────── Total: $0.21 ``` **Example: a 5-second hang-up** ``` Voice engine: $0.07 × 0.083 min = $0.006 LLM: $0.02 × 0.083 min = $0.002 Telephony: $0.015 × 0.083 min = $0.001 Short call surcharge (under 10s) = $0.015 ───────────────────────────────────────── Total: ~$0.024 ``` Voice calls always use Assistable's AI keys. (Bring-your-own-key only applies to chat. See below.) ### AI Chat Messages: billed per reply Every time your assistant **sends a reply** in a chat (SMS, Instagram, web chat, etc.), that's one billable message. * **Price: \$0.02 per AI reply.** * Messages *from* your customers are free. You only pay when the AI talks. * **Bring your own key (BYOK):** if you connect your own OpenAI / Anthropic / Google key, replies generated by *that provider's* models are **free**, because you're paying the AI company directly instead. The key only covers its own provider: an OpenAI key does **not** cover a Claude or Gemini assistant. Those still bill \$0.02 because they run on our keys. **Example:** Your assistant has 500 conversations this month and sends 1,200 replies. * Without your own key: 1,200 × $0.02 = **$24.00\*\* * With your own OpenAI key (and GPT-model assistants): **\$0.00** from us (OpenAI bills you directly) ### Knowledge Base: billed per lookup Your knowledge base is like a textbook your assistant can flip open mid-conversation. You pay only when it actually *opens the book*: * **Price: \$0.01 per query** (per lookup, not per minute, not per month). * A call where the assistant never needed the KB = \$0 for KB. * A call where the caller asked 3 hard questions and the assistant looked up 3 answers = \$0.03. **Example: a 1-minute call with 2 KB lookups** ``` Voice engine: $0.07 LLM: $0.02 Telephony: $0.015 KB-Usage: $0.01 × 2 queries = $0.02 ──────────────────────────────────────── Total: $0.125 ``` ### Observation / QA: billed per observer, per conversation Observers are like quality-control inspectors. You write rules ("flag calls where the customer sounds angry", "check the assistant offered the discount") and after every call or chat, each rule reads the transcript and grades it. * **Price: \$0.02 per observer per call/conversation.** Each rule = one observer = one AI evaluation. * 1 rule on a call = $0.02. 6 rules on a call = $0.12. No rules = \$0. **Example:** You have 4 monitor rules and your assistant handles 100 calls today: 4 observers × 100 calls × $0.02 = **$8.00\*\* ### Phone Numbers: billed monthly Renting a phone number is like a gym membership: a flat fee each month whether you use it a little or a lot. * **Price: \$2.50 per number per month.** ## Rebilling: How Agencies Charge Their Clients If you're an agency, your clients live in **sub-accounts**, and each sub-account has its **own wallet**. Rebilling means: when a client's assistant does work, *their* wallet gets charged at *your* prices, automatically. The difference between your price and our cost is your profit. ### Turning it on Rebilling has **two switches**, and both must be on: 1. **Master switch**: "rebill this sub-account: yes/no" 2. **Category switches**: one each for Voice minutes, Chat messages, Knowledge base, Observation, Phone numbers Common gotcha: master switch on but every category off = nothing gets rebilled. ### Setting your price: two ways For each category you pick **one** of: **Option A: Fixed price.** "I charge \$0.30 per minute. Period." Simple and predictable. You set the exact rate your client pays. **Option B: Percentage markup.** "Whatever it costs me, charge my client that **plus 40%**." This one is clever: it automatically adapts. If a call uses an expensive AI model, your cost goes up and your client's price goes up with it. Your margin stays 40% no matter what. ### Worked examples **Voice, fixed price.** You set \$0.30/min. Client gets a 2-minute call: * Your cost (from Part 1): \~\$0.21 * Client pays: $0.30 × 2 = **$0.60\*\* * Your profit: **\$0.39** on that call **Voice, 50% markup.** Same 2-minute call costs you \$0.25: * Client pays: $0.25 × 1.5 = **$0.375\*\* * Your profit: **\$0.125**, always exactly 50% of cost, even when the model price changes **Chat, fixed price.** You set \$0.04/message. Client's assistant sends 1,000 replies: * Your cost: 1,000 × $0.02 = $20 * Client pays: 1,000 × $0.04 = **$40\*\* * Your profit: **\$20** **Observation, 50% markup.** A chat gets graded by 1 observer: * Your cost: \$0.02 * Client pays: $0.02 + 50% = **$0.03\*\* **Phone number.** Our cost is $2.50/month; a typical resale price is $4.00/month → **\$1.50/month profit per number**. **Knowledge base: special case (current behavior).** KB rebilling works in two modes only: * **Percentage markup**, e.g. 50% markup: a lookup costs you $0.01, your client pays $0.015. * **No markup configured**: your client simply pays our cost (\$0.01 per lookup). You break even; they're never overcharged. Why no fixed \$ rate for KB right now? The old setting was "price per knowledge base" (a flat monthly idea), but KB is now billed **per lookup** (completely different units). To make sure nobody's client gets charged an old monthly-style price *per question*, custom flat KB rates are paused until everyone's settings are migrated. Percentage markup is the safe, recommended way to profit on KB. ### What your client sees Every rebilled charge shows up in the sub-account's transaction history with the same line-by-line receipt format, *at your prices*, not ours. Your client never sees Assistable's cost; you keep your margin private. ### Three honest rules of rebilling 1. **You can price below cost.** Want to charge your client \$0.01/min as a loss-leader? Allowed: it's your revenue, your call. 2. **\$0 means absorb.** Setting a price to zero means "don't charge my client for this. I'll eat the cost." 3. **Client wallets can go negative.** If a client's wallet hits \$0 mid-call, the call doesn't drop. The wallet goes negative and autopay (if they have it) refills it. ## Reading Your Receipt Every charge creates a transaction you can open. Here's a real voice-call receipt decoded: ``` AI Voice Call @ 0.871667 Minutes ← 52.3 seconds, billed exactly ├─ Voice engine: $0.07/min × 0.871667 = $0.0610 ├─ LLM: $0.02/min × 0.871667 = $0.0174 ├─ KB-Usage: $0.01 × 1 query = $0.0100 ← looked something up once ├─ Telephony: $0.015/min × 0.871667 = $0.0131 └─ Short call surcharge: not applied = $0 ← call was over 10 seconds Total: $0.1015 ``` And the matching observation receipt for the same call (if you had 3 rules): ``` AI Voice Observation @ 3 observers └─ Observation/QA: $0.02 / observer × 3 = $0.0600 ``` ## Quick-Reference Price Card | What | Unit | Our price | | --------------------- | ----------------------------- | -------------------------------------------- | | Voice engine | per minute | \$0.07 | | Voice LLM (the brain) | per minute | $0.02 to $0.05 (by model) | | Telephony | per minute | \$0.015 | | Short-call surcharge | per call under 10s | \$0.015 | | AI chat reply | per message | \$0.02 (free with your own matching API key) | | Knowledge base | per lookup | \$0.01 | | Observation / QA | per observer per conversation | \$0.02 | | Phone number | per month | \$2.50 | ## FAQ No. No connection, no charge. (Calls that connect but get hung up within 10 seconds bill a few cents. See short-call surcharge.) No. Only AI replies count. Check the assistant's model. Your OpenAI key only covers GPT models. Assistants running Claude, Gemini, or Kimi use our keys and bill normally. Switch those assistants to a GPT model or add keys for those providers too. Workspace = what you owe Assistable. Sub-account = what your client owes you. They're separate piles of tokens; one charge can legitimately appear in both ledgers (our cost on yours, your price on theirs). That's rebilling working, not a double charge. Yes, anytime. New prices apply to new activity from that moment on. Open the transaction: the line items show exactly what was billed and why. Still looks off? Contact support with the transaction ID and we'll trace it. # CLI Source: https://docs.assistable.ai/v3/cli The assistableai command-line interface — one command per v3 operation. The CLI (`assistableai`) gives you every v3 operation from your terminal or scripts, grouped by resource. Commands are generated from the OpenAPI spec. ```bash theme={null} npm install -g @assistableai/cli # or run without installing: npx @assistableai/cli --help ``` ## Authenticate ```bash theme={null} assistableai login --api-key ask_live_… --subaccount ``` Credentials are stored at `~/.assistableai/config.json` (mode `0600`). Resolution precedence for any command: explicit flag → environment (`ASSISTABLE_API_KEY`, `ASSISTABLE_SUBACCOUNT_ID`, `ASSISTABLE_BASE_URL`) → stored config. ```bash theme={null} assistableai whoami # show the active credentials (key masked) assistableai logout # delete stored credentials ``` ## Use it Commands are grouped by resource topic; add `--help` at any level: ```bash theme={null} assistableai --help # list topics assistableai assistants --help # commands in a topic assistableai assistants list --help # flags + args for one command ``` ```bash theme={null} # Read (table by default; --json for scripting) assistableai assistants list --limit 10 assistableai assistants get --json # Target a subaccount for one call assistableai contacts list -s # Write operations take a JSON body via -d / --data (or --data-file, '-' = stdin) assistableai contacts create -d '{"first_name":"Ada","email":"ada@example.com"}' echo '{"name":"Support bot"}' | assistableai assistants create --data-file - ``` ## Global flags | Flag | Description | | ----------------------- | ---------------------------------------------------- | | `--json` | Print the raw `{ data, error, request_id }` response | | `-s, --subaccount ` | Target subaccount (`X-Subaccount-Id`) for this call | | `--api-key ` | Override the stored/env key for this call | | `--base-url ` | Override the API base URL | | `-d, --data ` | JSON request body for write operations | | `--data-file ` | Read the JSON body from a file (`-` for stdin) | On an API error the message (with `request_id`) is written to stderr and the process exits non-zero, so it composes cleanly in shell pipelines and CI. # Errors Source: https://docs.assistable.ai/v3/errors Error envelope and status codes. All errors use the standard envelope: ```json theme={null} { "data": null, "error": { "code": "forbidden", "message": "Missing required scope: assistants:create" }, "request_id": "0f1c2d3e-..." } ``` Include the `request_id` when contacting support — it pinpoints the exact request. ## Status codes | Status | `error.code` | Meaning | | ------ | ----------------------------- | ------------------------------------------------------------------------- | | `400` | `validation_error` | Request body/params failed validation (see `error.details`) | | `400` | `subaccount_required` | No subaccount specified or resolvable | | `401` | `unauthorized` | Missing, malformed, expired, or revoked API key; or source IP not allowed | | `403` | `forbidden` | Key lacks the required scope | | `403` | `subaccount_forbidden` | Key is not authorized for the requested subaccount | | `404` | `not_found` | Resource not found within the resolved subaccount | | `429` | `rate_limited` | Burst or daily rate limit exceeded (see `Retry-After`) | | `502` | `call_failed` / `chat_failed` | Downstream provider error | ## Validation details `validation_error` responses include a `details` array of field issues: ```json theme={null} { "data": null, "error": { "code": "validation_error", "message": "Request validation failed", "details": [{ "path": "name", "message": "Required" }] }, "request_id": "..." } ``` # Export & Test Source: https://docs.assistable.ai/v3/export Download the full v3 API as an OpenAPI spec or a ready-to-run Postman collection, and import it into Postman, Hoppscotch, Insomnia, or any API client. The entire v3 API is available as machine-readable files you can import into your favourite API client and start testing in seconds. Pick whichever format your tool prefers — both cover **every** v3 endpoint. OpenAPI 3.1 spec. Import into **Hoppscotch, Insomnia, Postman, Bruno**, or generate client SDKs. Postman Collection v2.1 with Bearer auth and the `X-Subaccount-Id` header pre-wired. One-click import into **Postman**. If a link opens the JSON in your browser instead of downloading, right-click it and choose **Save Link As…**. ## Set two variables, then send any request Both files use placeholder variables so you only configure auth once. After importing, set: | Variable | What it is | Sent as | | -------------- | ------------------------------------------------------- | ------------------------------------------ | | `apiKey` | Your v3 key (`ask_live_…`) from **Settings → API Keys** | `Authorization: Bearer {{apiKey}}` | | `subaccountId` | The subaccount you're targeting | `X-Subaccount-Id: {{subaccountId}}` header | `baseUrl` defaults to `https://api.assistable.ai` and rarely needs changing. ## Import instructions 1. Download the **Postman Collection** above. 2. In Postman, click **Import** (top-left) and drop in the file. 3. Open the new **Assistable v3 API** collection → **Variables** tab. 4. Set `apiKey` and `subaccountId`, then **Save**. 5. Open any request and hit **Send**. Prefer the live, always-current spec? You can also import the **OpenAPI** file in Postman the same way — it auto-generates the same folders. 1. Download the **OpenAPI** file above. 2. In Hoppscotch, open the **Collections** panel → **Import / Export** → **Import from OpenAPI** and select the file. 3. Open the imported collection's **Headers/Authorization** and add your Bearer token plus the `X-Subaccount-Id` header. 4. Send any request. Hoppscotch can also import directly from a URL — paste the link to `openapi.json` from this page if you'd rather not download it. 1. Download the **OpenAPI** file above. 2. In Insomnia: **Create → Import → From File** and choose it. 3. Insomnia builds a request for every endpoint. Add your Bearer token and `X-Subaccount-Id` header, then send. The OpenAPI spec also feeds code generators. For example, with [`openapi-generator`](https://openapi-generator.tech): ```bash theme={null} openapi-generator-cli generate \ -i https://api.assistable.ai/v3/openapi.json \ -g typescript-fetch \ -o ./assistable-client ``` Or just call an endpoint directly: ```bash theme={null} curl https://api.assistable.ai/v3/assistants \ -H "Authorization: Bearer ask_live_xxx" \ -H "X-Subaccount-Id: sub_123" ``` # Introduction Source: https://docs.assistable.ai/v3/introduction The Assistable v3 public API — scoped keys, predictable rate limits, and an interactive reference. The **v3 API** is the supported, public interface to Assistable. Every endpoint lives under `/v3` so it's clear which version you're calling. ``` https://api.assistable.ai/v3 ``` ## What's new in v3 * **Scoped API keys** — a key is bound to a workspace and one or more subaccounts, with fine-grained `resource:action` scopes. * **Predictable rate limits** — per-subaccount burst and daily limits, with `X-RateLimit-*` headers on every response. * **Interactive reference** — try any endpoint from the browser using the **API Reference** tab. ## Quickstart In the dashboard, open **Settings → API Keys** and create a key. Copy it — the secret (`ask_live_…`) is shown only once. Pass the key as a Bearer token and select the target subaccount with the `X-Subaccount-Id` header. ```bash theme={null} curl https://api.assistable.ai/v3/assistants \ -H "Authorization: Bearer ask_live_xxx" \ -H "X-Subaccount-Id: sub_123" ``` Browse the **API Reference** tab and run requests directly in the playground. ## Conventions * All responses use the envelope `{ "data": ..., "error": ..., "request_id": ... }`. * Timestamps are ISO-8601 UTC. * `subaccount_id` in a request body is accepted as an alias for the `X-Subaccount-Id` header (and for the legacy `location_id`). # MCP Server Source: https://docs.assistable.ai/v3/mcp-server @assistableai/mcp — every v3 operation as a Model Context Protocol tool. The MCP server exposes every v3 API operation as a [Model Context Protocol](https://modelcontextprotocol.io) tool, so AI clients (Claude Desktop, Cursor, Claude Code, …) can manage assistants, contacts, calls, knowledge bases, and more on your behalf. ## Add it to your MCP client Most clients are configured with a JSON file. Point the command at `npx` so it always runs the latest published version: ```json theme={null} { "mcpServers": { "assistableai": { "command": "npx", "args": ["-y", "@assistableai/mcp"], "env": { "ASSISTABLE_API_KEY": "ask_live_…", "ASSISTABLE_SUBACCOUNT_ID": "" } } } } ``` | Client | Config file | | -------------- | -------------------------------------- | | Claude Desktop | `claude_desktop_config.json` | | Cursor | `.cursor/mcp.json` | | Claude Code | `claude mcp add` / project `.mcp.json` | ## Environment | Variable | Required | Purpose | | -------------------------- | -------- | ---------------------------------------------- | | `ASSISTABLE_API_KEY` | yes | Bearer key (`ask_live_…`) | | `ASSISTABLE_SUBACCOUNT_ID` | no | Default `X-Subaccount-Id` for every tool call | | `ASSISTABLE_BASE_URL` | no | Override (default `https://api.assistable.ai`) | Auth is applied on the underlying HTTP client, so it reaches every tool call. The server communicates over stdio and registers one tool per operation (e.g. `listAssistants`, `createContact`, `createCall`). Run it directly to sanity-check your env: `ASSISTABLE_API_KEY=ask_live_… npx -y @assistableai/mcp`. It exits with an error if the key is missing. # Platform Tools Source: https://docs.assistable.ai/v3/platform-tools Attach the standard tool kit to an assistant inline, by name The `platform_tools` field on the Assistants API attaches platform (prebuilt) tools by name in the same request that creates or updates an assistant — no per-tool assign calls, no id discovery. It is accepted on `POST /v3/assistants` and `PATCH /v3/assistants/{id}`. Successful `POST /v3/assistants` responses and `GET /v3/assistants/{id}` return it. ## Declarative semantics `platform_tools` is a declarative list scoped to the platform catalog: * **Omitted** — attachments are not touched at all. * **Provided** — the assistant's platform-tool attachments are made to match the list exactly: names in the list are attached, catalog tools missing from the list are detached. * **`[]`** — explicitly detaches every platform tool. Custom tools are never touched by this field, in either direction. They keep their own lifecycle via `POST /v3/tools/{id}/assign` and `DELETE /v3/tools/{id}/assign`, and the full attachment view (platform and custom) remains `GET /v3/assistants/{id}/tools`. Input order is irrelevant and duplicates are ignored; reads return names sorted alphabetically. Names resolve strictly inside the platform catalog — a custom tool that happens to reuse a catalog name can never be matched by this field. ## The catalog | Name | Does | | ---------------------------- | ----------------------------------------------------- | | `book_appointment` | Books an appointment on the connected calendar. | | `create_note` | Writes a note onto the contact record. | | `create_task` | Creates a follow-up task. | | `get_availability` | Reads open slots from the connected calendar. | | `get_user_calendar_events` | Lists the contact's upcoming appointments. | | `scrape_website` | Fetches and reads a web page. | | `search_the_web` | Runs a web search. | | `self_schedule` | Lets the assistant schedule its own follow-up action. | | `send_email` | Sends an email to the contact. | | `update_appointment_details` | Reschedules or edits an existing appointment. | | `update_user_details` | Updates fields on the contact record. | `call_user`, `end_call`, and `press_key` are **not** attachable through this field. `call_user` remains visible in the tools list and attachable via `POST /v3/tools/{id}/assign`; call-control tools are managed by the platform. Validation reports every offending name in a single 400 response, distinguishing unknown names from deliberately excluded ones. ## Example ```json theme={null} PATCH /v3/assistants/{id} { "platform_tools": ["book_appointment", "get_availability", "send_email"] } ``` A subsequent `GET /v3/assistants/{id}` returns: ```json theme={null} { "platform_tools": ["book_appointment", "get_availability", "send_email"] } ``` ## Notes * Tool changes made through this field propagate to the voice runtime via the assistant's automatic re-publish, same as every other assistant edit. * Custom-tool assignment via the assign endpoint reaches live voice calls on the assistant's next publish — a pre-existing behavior documented here for completeness. # Python SDK Source: https://docs.assistable.ai/v3/python-sdk Official assistableai package — typed operation functions, models, and an MCP server for the v3 API. The Python SDK wraps every v3 endpoint as a typed function, generated from the same OpenAPI spec that powers the **API Reference**. Install it, call `configure()` once, and call the operation functions. The same package also ships an optional [MCP server](#mcp-server). ```bash theme={null} pip install assistableai # or: uv add assistableai ``` Requires Python 3.10+. ## Configure ```python theme={null} import assistableai from assistableai import api client = assistableai.configure( api_key="ask_live_…", # or env ASSISTABLE_API_KEY subaccount_id="", # optional default X-Subaccount-Id # base_url defaults to https://api.assistable.ai ) ``` `configure()` sets `Authorization: Bearer ` and (when provided) `X-Subaccount-Id` on every request, and remembers the client process-globally. Arguments fall back to the environment (`ASSISTABLE_API_KEY`, `ASSISTABLE_SUBACCOUNT_ID`, `ASSISTABLE_BASE_URL`). Prefer an explicit instance? Use `AssistableAI(...)` directly — it takes the same arguments and exposes the same `.raw` client. ```python theme={null} from assistableai import AssistableAI client = AssistableAI(api_key="ask_live_…", subaccount_id="") ``` ## Make a request Operations live under `api..`. Pass `client=client.raw` and the operation's parameters. Every operation returns the full v3 envelope — `{ data, error, request_id }` — as a typed model: ```python theme={null} result = api.assistants.list_assistants.sync(client=client.raw, limit=2) if result.error: print(f"Request {result.request_id} failed:", result.error) else: for assistant in result.data: print(assistant.id, assistant.name) ``` Path parameters are positional; query params and bodies are keyword arguments: ```python theme={null} assistant = api.assistants.get_assistant.sync("", client=client.raw) contact = api.contacts.create_contact.sync( client=client.raw, body={"first_name": "Ada", "email": "ada@example.com"}, ) ``` Each operation also exposes: * **`sync_detailed(...)`** — returns the HTTP status code and headers alongside the parsed body. * **`asyncio(...)` / `asyncio_detailed(...)`** — `await`-able variants for async code. ```python theme={null} result = await api.assistants.list_assistants.asyncio(client=client.raw, limit=2) ``` The import path `from assistableai._client.api.assistants import list_assistants` also works if you prefer importing operations directly. ## Per-call subaccount override Pass `x_subaccount_id=` to target a different subaccount for a single call without changing the global default: ```python theme={null} api.assistants.list_assistants.sync(client=client.raw, limit=10, x_subaccount_id="") ``` ## MCP server The package bundles an [MCP](https://modelcontextprotocol.io) server that exposes every v3 operation as a tool. Install the optional extra: ```bash theme={null} pip install "assistableai[mcp]" ``` Run it directly to sanity-check your env: ```bash theme={null} ASSISTABLE_API_KEY=ask_live_… assistableai-mcp # or: python -m assistableai.mcp ``` Add it to an MCP client (Claude Desktop, Cursor, Claude Code, …). Using [`uvx`](https://docs.astral.sh/uv/) means no separate install step: ```json theme={null} { "mcpServers": { "assistableai": { "command": "uvx", "args": ["--from", "assistableai[mcp]", "assistableai-mcp"], "env": { "ASSISTABLE_API_KEY": "ask_live_…", "ASSISTABLE_SUBACCOUNT_ID": "" } } } } ``` | Variable | Required | Purpose | | -------------------------- | -------- | ---------------------------------------------- | | `ASSISTABLE_API_KEY` | yes | Bearer key (`ask_live_…`) | | `ASSISTABLE_SUBACCOUNT_ID` | no | Default `X-Subaccount-Id` for every tool call | | `ASSISTABLE_BASE_URL` | no | Override (default `https://api.assistable.ai`) | Auth is applied on the underlying HTTP client, so it reaches every tool call. The server registers one tool per operation (e.g. `listAssistants`, `createContact`, `createCall`). The typed surface (operation functions + models) is generated from `spec/openapi.json` and kept in lockstep with the API. See the **API Reference** tab for the full list of operations and their shapes. # Rate limits Source: https://docs.assistable.ai/v3/rate-limits Per-subaccount burst and daily limits, with headers and 429 handling. Limits are enforced per **workspace + subaccount** — not per key. Creating more keys does **not** raise your limit; all keys for a subaccount share the same budget. | Window | Default limit | | ------ | -------------------------------- | | Burst | **150 requests / 10 seconds** | | Daily | **100,000 requests / day** (UTC) | ## Response headers Every response includes: | Header | Meaning | | ----------------------------- | ------------------------------------- | | `X-RateLimit-Limit` | Burst limit | | `X-RateLimit-Remaining` | Burst requests remaining | | `X-RateLimit-Reset` | Seconds until the burst window resets | | `X-RateLimit-Daily-Limit` | Daily quota | | `X-RateLimit-Daily-Remaining` | Daily requests remaining | | `X-RateLimit-Daily-Reset` | Seconds until the daily quota resets | ## When you're limited Over-limit requests return `429` with a `Retry-After` header (seconds): ```json theme={null} { "data": null, "error": { "code": "rate_limited", "message": "Rate limit exceeded (burst). Retry after 7s." }, "request_id": "..." } ``` Back off for `Retry-After` seconds, then retry. ## Higher limits Need more headroom? Enterprise workspaces and individual subaccounts can have their burst and daily limits raised. Contact support with your workspace and subaccount IDs. # TypeScript SDK Source: https://docs.assistable.ai/v3/typescript-sdk Official @assistableai/sdk — typed operation functions and models for the v3 API. The TypeScript SDK wraps every v3 endpoint as a typed function, generated from the same OpenAPI spec that powers the **API Reference**. Install it, call `configure()` once, and use the operation functions. ```bash theme={null} npm install @assistableai/sdk # or: pnpm add @assistableai/sdk / yarn add @assistableai/sdk ``` ## Configure ```ts theme={null} import { configure, listAssistants } from "@assistableai/sdk"; configure({ apiKey: process.env.ASSISTABLE_API_KEY!, // ask_live_… subaccountId: process.env.ASSISTABLE_SUBACCOUNT_ID, // optional default X-Subaccount-Id // baseUrl defaults to https://api.assistable.ai }); ``` `configure()` sets `Authorization: Bearer ` and (when provided) `X-Subaccount-Id` on every request. ## Make a request Every operation returns the full v3 envelope — `{ data, error, request_id }` — typed, so destructure what you need: ```ts theme={null} const { data, error, request_id } = await listAssistants({ limit: 2 }); if (error) { console.error(`Request ${request_id} failed:`, error); } else { for (const assistant of data) console.log(assistant.id, assistant.name); } ``` Path parameters are positional; query params and bodies are typed objects: ```ts theme={null} import { getAssistant, createContact } from "@assistableai/sdk"; const { data: assistant } = await getAssistant(""); const { data: contact } = await createContact({ first_name: "Ada", email: "ada@example.com", }); ``` ## Per-call subaccount override Pass the `X-Subaccount-Id` header argument to target a different subaccount for a single call (without changing the global default): ```ts theme={null} await listAssistants({ limit: 10 }, { "X-Subaccount-Id": "" }); ``` The typed surface (operation functions + models) is generated from `spec/openapi.json` and kept in lockstep with the API. See the **API Reference** tab for the full list of operations and their shapes. # Voice Enabled Chat Widget Source: https://docs.assistable.ai/v3/voice-enabled-chat-widget Complete guide to deploying and configuring the Chat Widget with voice conversation support. The Chat Widget supports both text chat and live voice conversations in the browser. Visitors can type or speak to your assistant, switching between modes mid-conversation without losing context. ## Overview The widget functions as a 24/7 front desk on your website: * Greets visitors with suggested prompts * Answers from your knowledge base * Supports both typed (Chat) and spoken (Voice) conversations * Collects information through forms * Escalates to human agents when needed ## Chat vs Voice | Mode | Description | Best For | | --------- | ---------------------------------- | ---------------------------------------------------- | | **Chat** | Typed messages, like any messenger | Quick questions, async support, mobile | | **Voice** | Spoken conversation in the browser | Hands-free interaction, faster back-and-forth, demos | Visitors can switch between modes during a conversation. The assistant maintains full context when switching from chat to voice or vice versa. ## Widget Templates Four starter templates optimize the widget for different use cases: | Template | Optimized For | | ------------ | ----------------------------------------------------- | | **Commerce** | Online stores (product help, orders, recommendations) | | **Support** | Help desks (answers, tickets, human handoff) | | **Sales** | Lead capture (qualifying questions, booking) | | **General** | Blank, fully-configurable starting point | ## Enabling Voice Voice conversations require three conditions: 1. The assigned assistant must have a **published voice agent** 2. The widget must have `voiceEnabled` set to true 3. The hosting page must use **HTTPS** (browsers block microphone access on HTTP) When these conditions are met, the Chat | Voice toggle appears automatically. ### Publishing a Voice Agent Navigate to Assistants and create a new assistant or open an existing one. Open the Voice Lab tab. The assistant ships with a default voice. Click the voice name to change it, and use Start Call to test it. Click Publish. This provisions the voice agent on the backend and makes voice available to any widget using this assistant. The Voice toggle only appears when the assigned assistant has a published voice agent. Unpublished assistants show chat only. ## Knowledge Base Integration The knowledge base serves as the assistant's handbook. Both chat and voice answer from the same knowledge base with identical accuracy. ### Context-Aware Lookups The assistant rewrites follow-up questions to include full context before searching: * Visitor: "What are your hours?" * Visitor: "What about the Batavia location?" * Internal rewrite: "What are the hours for the Batavia location?" This ensures follow-up questions retrieve relevant answers instead of hallucinated responses. ### Multi-Angle Search The system searches the knowledge base multiple ways and merges the best results, improving answer relevance and reducing misses. ### Fallback Behavior When a question falls outside the knowledge base scope, the assistant returns your configured fallback message instead of inventing an answer. Knowledge base lookups are billed at \$0.01 per lookup. The widget only performs lookups when needed (simple greetings like "hi" trigger no lookup). ## Widget Tabs The widget includes five optional tabs controlled by the `visibleTabs` setting: | Tab | Purpose | | ------------ | ---------------------------------------- | | **Home** | Action cards and suggested prompts | | **Messages** | Conversation thread (chat and voice) | | **News** | Product updates and announcements | | **Roadmap** | Upcoming features with status and voting | | **Help** | Live search over your knowledge base | When only one tab is visible, the bottom navigation auto-hides for a clean chat interface. ### Teaser Greeting An optional Intercom-style greeting card appears above the launcher bubble with clickable suggestion chips. Configure the color with `teaserColor` (text auto-adjusts for contrast). ### Roadmap Statuses Roadmap items display one of four states: | Status | Meaning | | ------------- | ---------------------- | | `considering` | Gathering interest | | `planned` | Committed, not started | | `in_progress` | Currently being built | | `shipped` | Live | ## Action Cards and Forms The Home tab displays action cards that operate in three modes: | Mode | Behavior | | -------- | -------------------------------------------------------- | | **chat** | Opens conversation, optionally with a pre-seeded message | | **form** | Displays a form, collects answers, submits to CRM | | **link** | Opens a URL | ### Form Field Types | Field Type | Control | | ------------ | --------------------------------------- | | **text** | Single-line text box | | **email** | Email-validated text box | | **textarea** | Multi-line text box | | **select** | Dropdown menu | | **radio** | Single selection from list | | **checkbox** | Yes/no toggle | | **rating** | Star or emoji rating | | **nps** | 0-10 recommendation scale | | **scale** | Configurable number scale (default 1-5) | | **priority** | Low / Normal / High / Urgent | Each field supports: * **required** validation * **placeholder** text * **maps\_to** for CRM field mapping NPS fields default to 0-10 range. Scale fields default to 1-5 but accept custom `min` and `max` values. ### In-Chat Action Cards When the assistant executes a tool, results render as interactive cards: **Commerce Cards** * Browse products (swipeable carousel) * Order management (list, status, cancel, return) * Checkout (start, apply discount, upsell) * Billing (subscription status, invoices) **Support Cards** * Ticket management (create, check status, list) * Feedback submission * Booking (available slots, schedule) * Email verification * Human handoff Cards only appear when the assigned assistant has the corresponding tool enabled and your store or helpdesk is connected. ## Human Handoff The widget supports three handoff modes via the `handoffMode` setting: | Mode | Visitor Experience | | --------------- | --------------------------------------------------- | | **support** | "Talk to a human" button with "Agent joined" banner | | **transparent** | Human replies appear as normal assistant messages | | **disabled** | No handoff surface (pure self-serve) | ### Escalation Cascade Handoff requests fan out simultaneously across: * Dashboard inbox * Email * Slack * Configured webhooks This escalation path operates even when the account is out of credit, ensuring leads never silently fail. ### Live Agent Indicator When a human joins the thread, the header displays "Live agent connected" so visitors know they are speaking with a person. ### Office Hours Configure office hours to display an honest "we're away" state outside business hours instead of implying immediate availability. ### Bug Reports Enable `bugReportEnabled` to add a one-click screenshot capture tool for visitors to report issues. ## Pre-Chat Form Enable `requirePreChatForm` to collect visitor information before starting the conversation. Choose any combination of: * Name * Email * Phone Visitors complete a short form (with custom heading and subheading) before the chat opens. Disabled by default. ## Configuration Reference ### Appearance Settings | Setting | Controls | Options | | --------------------- | ------------------------------- | --------------------------------------------------------- | | `color` | Primary brand color | Any hex (default black) | | `theme` | Light or dark mode | `light` / `dark` | | `shape` | Corner style | `rounded` / `sharp` / `soft` | | `position` | Launcher bubble placement | `bottom-right` / `bottom-left` / `top-right` / `top-left` | | `buttonIcon` | Launcher icon | `chat` / `message` / `question` / `headset` / `sparkles` | | `launcherSize` | Bubble size | `sm` / `md` / `lg` | | `logoUrl` | Brand logo | URL | | `aiAvatarUrl` | Bot avatar (falls back to logo) | URL | | `teaserColor` | Greeting card color | Any hex | | `headerSubline` | Subtitle under title | Text | | `showBranding` | "Powered by" footer | Boolean | | `showOnlineIndicator` | Status indicator in header | Boolean | ### Messaging Settings | Setting | Purpose | | ------------------- | ------------------------------ | | `greetingMessage` | Initial assistant message | | `promptMessage` | Help prompt text | | `prompts` | Suggested question chips | | `teaserGreeting` | Pop-up card greeting | | `teaserSuggestions` | Pop-up card chips | | `fallbackMessage` | Response when unable to answer | | `aiDisclaimer` | AI conversation notice | | `menuHeader` | Home tab heading | | `menuSubheader` | Home tab subheading | ### Behavior Settings | Setting | Effect | | | ----------------------- | -------------------------------- | ------------ | | `autoOpen` | Auto-open widget on page load | | | `enableMemory` | Remember visitor across sessions | | | `persistHistory` | Keep thread across page loads | | | `notificationSound` | Play sound on new replies | | | `notificationSoundKind` | Sound type | | | `voiceEnabled` | Allow Chat | Voice toggle | | `previewMode` | Inline editor preview | | `voiceEnabled` is server-authoritative. Voice only appears when the assigned assistant has a published voice agent, regardless of embed settings. ## Installation Navigate to Widgets, create a new Chat Widget V2, and assign a voice-enabled assistant. Open the Install section and copy the provided script snippet. Paste the snippet before the closing `` tag on your website. ```html theme={null} ``` The Chat | Voice toggle appears automatically when the assigned assistant has a published voice agent. The hosting page must use HTTPS. Browsers block microphone access on HTTP pages. ## Editor Sections The Chat Widget V2 editor includes six configuration sections: | Section | Configuration | | ------------------------ | ----------------------------------------------------------------------------------------------------- | | **Assistant** | Assigned assistant, greeting, intro message, prompt chips | | **Tabs & content** | Enable/disable tabs, import news feeds (RSS/Atom/JSON), import help content (articles, docs, sitemap) | | **Appearance** | Display name, header subline, brand name, logos, colors | | **Integrations & tools** | Slack notifications, tool connections | | **Behavior** | Voice toggle, human handoff mode, AI disclaimer, allowed domains | | **Install** | Embed snippet | A readiness checklist at the top flags incomplete configuration (e.g., "Voice enabled but no voice agent published", "Human handoff enabled but no Slack connected"). # Voice Settings Source: https://docs.assistable.ai/v3/voice-settings Greeting modes, opening messages, and voicemail behavior on the Assistants API The `voice_settings` object on the Assistants API controls how an assistant opens a phone call and what it does when it reaches voicemail. It is accepted on `POST /v3/assistants` and `PATCH /v3/assistants/{id}`. Successful `POST /v3/assistants` responses and `GET /v3/assistants/{id}` return it (the list endpoint does not include it). ## Three concepts, kept distinct The API deliberately separates three things that are easy to conflate: * **Greeting text** — `inbound_greeting` / `outbound_greeting`. Context text that feeds the `{{greeting}}` template variable your prompt can reference. It is *not* spoken automatically. These remain writable via the top-level body fields; inside `voice_settings` they appear read-only for convenience. * **Opening message** — what the assistant literally says first on a call, per direction (`inbound_opening_message` / `outbound_opening_message`). Only used in `fixed` greeting mode. * **Voicemail behavior** — `voicemail_message`. When voicemail is detected: an empty or `null` value means the assistant hangs up; a non-empty value is spoken to the voicemail, after which the assistant stops. ## Greeting modes | `greeting_mode` | Behavior | | --------------- | -------------------------------------------------------------- | | `dynamic` | The AI generates a natural opener per call (default). | | `fixed` | The assistant speaks your configured opening message verbatim. | | `contact_first` | The assistant stays silent until the contact speaks. | Rules the API enforces: 1. `fixed` mode requires at least one opening message. Switching an existing assistant to `fixed` keeps its stored messages, so a mode-only update is valid when messages already exist. 2. Opening messages are only accepted while the effective mode is `fixed` — set `greeting_mode: "fixed"` in the same request if needed. 3. In `fixed` mode, sending `null` for one direction clears it, as long as at least one opening message remains. Template variables inside opening messages (for example a contact first-name placeholder) are passed through verbatim and resolve per call. ## Example Request — put an assistant into fixed mode with per-direction openers and a voicemail message: ```json theme={null} PATCH /v3/assistants/{id} { "voice_settings": { "greeting_mode": "fixed", "inbound_opening_message": "Thanks for calling Acme — this is Ava. How can I help?", "outbound_opening_message": "Hi {{contact.first_name}}, this is Ava from Acme!", "voicemail_message": "Sorry we missed you — we'll try again soon." } } ``` Response — `GET /v3/assistants/{id}` then returns: ```json theme={null} { "voice_settings": { "greeting_mode": "fixed", "inbound_opening_message": "Thanks for calling Acme — this is Ava. How can I help?", "outbound_opening_message": "Hi {{contact.first_name}}, this is Ava from Acme!", "inbound_greeting": null, "outbound_greeting": null, "voicemail_message": "Sorry we missed you — we'll try again soon.", "enable_voicemail_detection": false } } ``` ## Notes * `enable_voicemail_detection` records intent and is returned on read, but voicemail detection is currently platform-managed — the flag does not yet change runtime behavior. * Reverting an assistant to a previous version does **not** restore `voice_settings`; greeting mode, opening messages, and voicemail behavior keep their current values. # Voice Studio and Multi-Provider Speech Source: https://docs.assistable.ai/v3/voice-studio Configure text-to-speech providers, speech-to-text models, noise suppression, and voice tuning in the redesigned Voice Studio. The voice pipeline is now multi-provider. You can choose from five text-to-speech engines, six speech-to-text models, and two noise suppression engines, all configured in a redesigned Voice Studio experience. ## Text-to-Speech Providers Assistable supports five TTS providers, each with its own model lineup and tuning controls. ### Rime (Recommended) Rime is the recommended provider for most use cases. Models: * **Coda** (new default): flagship conversational model. * **Natural**: balanced quality and latency. * **Natural HD**: higher fidelity. * **Arcana v3**: expressive character voices. * **Kokoro**: multilingual support. All Rime models support Expressive Mode (context-aware emotion) and Language Boost across 11 languages. ### ElevenLabs ElevenLabs offers the full model family with fine-grained tuning: * **Eleven v2**: flagship quality. * **Flash v2 / v2.5**: low latency. * **Turbo v2 / v2.5**: ultra-low latency. * **Multilingual v2**: 29 languages. Tuning controls: Stability, Similarity Boost, Style, Speaker Boost. ### MiniMax MiniMax models: * **speech-2.8-turbo**: fast conversational speech. * **speech-2.5-hd**: high-definition audio. ### Amazon Polly AWS Polly provides a wide range of voices across 30+ languages with Neural and Standard engines. ### Microsoft Azure Azure TTS offers locale-precise voices with automatic lowest-latency region selection. ### Inworld Inworld models: * **Mini**: lightweight conversational model. * **Max**: higher expressiveness. ### Resemble Resemble models: * **Turbo**: fast synthesis. * **Rapid**: ultra-low latency. ## Speech-to-Text Models Your assistant's hearing is now configurable. Choose from six transcription engines. ### Deepgram Flux (Recommended) Deepgram Flux is the new recommended default. It is a conversation-native model with fine-grained end-of-turn controls, so the assistant knows exactly when the caller has finished speaking. Supports 10 languages plus auto-detect and multilingual code-switching. ### Deepgram Nova-3 Nova-3 supports 80+ languages and locales with Smart Format (automatic punctuation, capitalization, numeral conversion) and Keyterm Boost (bias transcription toward your product names and industry jargon). ### Deepgram Nova-2 Nova-2 offers broad language coverage with Smart Format and numeral conversion. ### AssemblyAI Universal-Streaming Streaming transcription with configurable turn-silence thresholds. Supports 6 languages plus auto-detect. ### Azure Fast Locale-precise transcription with automatic lowest-latency region selection. ## Noise Suppression Noise suppression cleans up caller audio before it reaches transcription. Enable it for calls from cars, cafés, and job sites. ### Krisp (Recommended) Industry-leading voice isolation. Krisp removes background noise while preserving caller speech. ### DeepFilterNet DeepFilterNet offers adjustable attenuation limits and an advanced mode for full control over how aggressively noise is removed. ## Voice Studio UI The Voice Studio experience is redesigned around three workspaces: ### Voice Settings Panel The Voice Settings panel is your central configuration workspace. It includes: * Provider and model selection (TTS and STT). * Voice tuning controls (Stability, Similarity Boost, Style, Speaker Boost for ElevenLabs; Expressive Mode and Language Boost for Rime). * Noise suppression engine selection and configuration. * Interruption and turn-taking controls (end-of-turn thresholds, silence detection). * Auto-save: a live Saving indicator appears as you edit, then changes to Saved. Nothing goes live to callers until you press Publish. ### Voice Library Browse the multi-provider voice catalog: * **Instant search**: search by voice name, voice ID, or accent. * **Filters**: filter by provider, language, or accent. * **Curated tabs**: Recommended (staff-curated voices) and Favorites (your starred voices). * **One-click previews**: play any voice inline. * **Community voting**: upvote voices to help surface the best options. ### Compare Dock Shortlist up to 8 voices and compare them side by side: * **Back-to-back playback**: play voices in sequence with auto-advance. * **Adjustable speed**: 0.75× to 2× playback speed. * **One-click apply**: select the winner and apply it to your assistant. ### My Voices Manage custom voices: * **Import a recording**: upload an audio file to clone a voice. * **Clone from a sample**: provide a short sample and generate a custom voice. * **Duplicate by ID**: copy a voice by its ID. Custom voices are private to your workspace. ## How to Configure Voice Settings Open any assistant in your portal and navigate to the Voice Settings panel. Click Change voice to open the Voice Library. Browse, search, or filter to find a voice. Play previews, add voices to the Compare dock, and select the one you want. In the Voice Settings panel, select a speech-to-text model from the dropdown. Configure end-of-turn thresholds, Smart Format, or Keyterm Boost if the model supports them. Toggle noise suppression on and choose Krisp or DeepFilterNet. If using DeepFilterNet, adjust the attenuation limit and enable advanced mode if needed. If your provider supports tuning (ElevenLabs, Rime), adjust Stability, Similarity Boost, Style, Speaker Boost, Expressive Mode, or Language Boost. Press Publish to make the changes live on calls. The assistant will use the new voice, transcription model, and noise suppression settings on the next call. ## Notes Voice changes do not affect calls in progress. The new settings apply to calls that start after you press Publish. Custom voices (cloned or imported) are private to your workspace and do not appear in the public Voice Library. Noise suppression adds a small amount of latency (typically under 100ms). If you are optimizing for the lowest possible latency, test with and without noise suppression to measure the impact. # Zapier (Beta) Source: https://docs.assistable.ai/v3/zapier Connect Assistable to 8,000+ apps. Trigger on calls, conversations, and alerts. Place AI calls and update contacts from anywhere. Our Zapier integration puts Assistable in the middle of your stack. A completed call can write to your CRM. A new lead in your CRM can get an AI phone call thirty seconds later. No code either way. The integration is in **beta** and invite-only. Add it to your Zapier account with [this invite link](https://zapier.com/developer/public-invite/243635/9ed48f96fb7ec82f2581603b9d77eac3/) and it appears in your Zap editor like any other app. ## Connect your account Accept the [invite link](https://zapier.com/developer/public-invite/243635/9ed48f96fb7ec82f2581603b9d77eac3/) once per Zapier account. Create a v3 API key in the dashboard under **Integrations → API Key** (see [Authentication](/v3/authentication)). Read-write role recommended. In any Zap step, choose **Assistable AI** and paste the key when prompted. Only using a key that spans multiple subaccounts? Add the **Subaccount ID** too. Single-subaccount keys skip this. ## What you can build | When this happens in Assistable... | ...do this anywhere | Or the reverse | | -------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------- | | Call completes (with sentiment + transcript) | Post the summary to Slack, log to your CRM | New CRM lead → **Place AI Voice Call** | | Monitor alert fires (compliance, escalation) | Page the on-call, open a ticket | Ticket resolved → **Update Alert Status** | | Appointment booked by an assistant | Add to Google Calendar, notify the team | Form submission → **Create Appointment** | | New conversation starts | Enrich the contact, tag the lead | Support reply drafted → **Send Message** or **Generate AI Reply** | | New contact created | Sync to your CRM | Any app → **Find-or-Create Contact** | **Triggers:** New Contact, New Call (status, sentiment, and duration filters), New Conversation (channel filter), New Monitor Alert (severity, category, assistant filters), New Appointment. **Actions:** Place AI Voice Call, Create/Update Contact, Add Note to Contact, Send Message, Generate AI Reply, Create/Update Appointment, Create Tag, Add Text or URL to Knowledge Base, Update Alert Status, Create Assistant. **Searches:** Find Contact, Find Assistant, Find Conversation, Get Call by ID (transcript, recording, cost, sentiment). ## Notes for the beta * Triggers poll on your Zapier plan's polling interval (1 to 15 minutes depending on plan). * Rate limits are the standard [v3 limits](/v3/rate-limits), shared per subaccount. * Something off? Report it in [Discord](https://discord.gg/5v4WSM3YwP) **#get-help**. Fixes ship fast and your Zaps pick them up automatically. # Available Variables Reference Source: https://docs.assistable.ai/variables/available-variables Complete reference of all dynamic variables available in Assistable.ai prompts and workflows. Variables use the `{{variable_name}}` syntax and are replaced with real values at runtime. ## Session Variables | Variable | Description | Example | | -------------- | ------------------------------- | ------------------------ | | `location_id` | Current sub-account/location ID | `abc123def456` | | `account` | Account name | `Acme Corp` | | `assistant_id` | AI assistant ID | `asst_001` | | `contact_id` | Contact ID | `con_12345` | | `calendar_id` | Linked calendar ID | `cal_abc123` | | `direction` | Conversation direction | `inbound` | | `channel` | Communication channel | `sms` | | `current_date` | Date at session start | `2026-02-27` | | `current_time` | Time at session start | `14:30:00` | | `timezone` | Session timezone | `America/New_York` | | `phone_id` | Phone number ID | `ph_555001` | | `to` | Destination number | `+15551234567` | | `from` | Originating number | `+15559876543` | | `memory` | Persistent memory content | *(text)* | | `greeting` | Greeting message | `Hello! How can I help?` | ## Right Now Variables Dynamic values computed at execution time. Prefixed with `right_now.` | Variable | Description | Example | | ------------------------------------------------- | ----------------- | ------------------- | | `right_now.current_date` | Formatted date | `February 27, 2026` | | `right_now.current_time` | Formatted time | `2:30 PM` | | `right_now.day_name` | Day of the week | `Friday` | | `right_now.month` | Month name | `February` | | `right_now.year` | Current year | `2026` | | `right_now.am_pm` | AM or PM | `PM` | | `right_now.timezone` | Timezone name | `America/New_York` | | `right_now.tomorrow_date` | Tomorrow's date | `02/28/2026` | | `right_now.mon_date` through `right_now.sun_date` | This week's dates | `02/23/2026` | ## Contact Variables CRM contact fields. Prefixed with `contact.` | Variable | Description | Example | | --------------------- | ---------------- | ------------------------------- | | `contact.first_name` | First name | `John` | | `contact.last_name` | Last name | `Smith` | | `contact.full_name` | Full name | `John Smith` | | `contact.phone` | Formatted phone | `(555) 123-4567` | | `contact.phone_raw` | Raw E.164 phone | `+15551234567` | | `contact.email` | Email address | `john@example.com` | | `contact.timezone` | Contact timezone | `America/Chicago` | | `contact.address1` | Street address | `123 Main St` | | `contact.city` | City | `Dallas` | | `contact.state` | State | `TX` | | `contact.postal_code` | ZIP code | `75201` | | `contact.source` | Lead source | `Website Form` | | `contact.tags` | Assigned tags | `vip, returning-client` | | `contact.notes` | Contact notes | `Preferred callback after 5 PM` | ## Location Variables Business and sub-account info. Prefixed with `location.` | Variable | Description | Example | | --------------------- | ---------------- | ---------------------- | | `location.name` | Business name | `Acme Corp - Downtown` | | `location.address` | Street address | `456 Commerce Blvd` | | `location.city` | City | `Austin` | | `location.state` | State | `TX` | | `location.website` | Website URL | `https://acmecorp.com` | | `location.timezone` | Timezone | `America/Chicago` | | `location.phone` | Phone number | `(555) 987-6543` | | `location.email` | Email | `info@acmecorp.com` | | `location.first_name` | Owner first name | `Jane` | | `location.last_name` | Owner last name | `Doe` | ### Business Profile (`location.business.*`) | Variable | Description | | --------------------------- | ---------------- | | `location.business.name` | Business name | | `location.business.address` | Business address | | `location.business.website` | Business website | | `location.business.email` | Business email | ### Social Links (`location.social.*`) | Variable | Description | | --------------------------- | ------------- | | `location.social.facebook` | Facebook URL | | `location.social.instagram` | Instagram URL | | `location.social.linkedin` | LinkedIn URL | | `location.social.youtube` | YouTube URL | | `location.social.twitter` | Twitter/X URL | ## User Variables Assigned user/agent info. Prefixed with `user.` | Variable | Description | Example | | ----------------- | ------------ | -------------------- | | `user.name` | Display name | `Sarah Johnson` | | `user.first_name` | First name | `Sarah` | | `user.email` | Email | `sarah@acmecorp.com` | | `user.phone` | Phone | `(555) 222-3344` | | `user.role` | Role name | `Admin` | ## Custom Values User-defined fields. Prefixed with `custom_values.` | Variable | Description | Example | | ---------------------------- | ----------------- | ------------------------------- | | `custom_values.company_name` | Your company name | `Acme Corporation` | | `custom_values.timezone` | Business timezone | `America/New_York` | | `custom_values.booking_link` | Scheduling link | `https://calendly.com/acmecorp` | | `custom_values.office_hours` | Business hours | `Mon-Fri 9AM-5PM EST` | Create custom values in your CRM settings and reference them with `{{custom_values.your_field_name}}`. This keeps prompts dynamic and easy to update across all assistants.