### Example JSON for Start Conversational Pathway Node Source: https://docs.bland.ai/api-v1/post/update_pathways Illustrates the structure for a 'Start' node, which marks the beginning of a conversational flow. It includes basic identification and initial conversational text. ```json { "id": "1", "type": "Default", "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true } } ``` -------------------------------- ### Example Response for Create Knowledge Base Source: https://docs.bland.ai/api-v1/post/vectors An example of the successful response returned after creating a knowledge base. ```json { "vector_id": "KB-55e64dae-1585-4632-ae97-c909c288c6bc" } ``` -------------------------------- ### Example JSON Response for Get Pathway Versions Source: https://docs.bland.ai/api-v1/get/pathway_versions An illustrative JSON array demonstrating the expected structure and content of the response when successfully retrieving pathway versions, showing two example pathway version objects. ```JSON [ { "id": "v1_abc123", "version_number": 1, "created_at": "2024-03-05T12:00:00Z", "name": "Initial Version", "is_latest": false }, { "id": "v2_def456", "version_number": 2, "created_at": "2024-03-06T14:30:00Z", "name": "Updated Flow", "is_latest": true } ] ``` -------------------------------- ### Conversational Pathway Node JSON Examples Source: https://docs.bland.ai/api-v1/get/all_pathway Illustrates various types of nodes used in a conversational pathway, including their structure and data properties. Examples cover Start, Default, End, Webhook, Knowledge Base, Global, and Transfer Call nodes. ```json { "id": "1", "type": "Default", "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true } } ``` ```json { "id": "randomnode_1710288871721", "type": "Default", "data": { "name": "New Node", "text": "Select a node or edge and press backspace to remove it", "globalPrompt": "This is a phone call. Do not use exclamation marks.\n\nConvert 24HR format timings to 12 HR format - e.g 14:00 should be written as 2 PM." } } ``` ```json { "id": "randomnode_1710288752186", "type": "End Call", "data": { "name": "End call", "prompt": "Say goodbye to the user" } } ``` ```json { "id": "randomnode_1710288752186", "type": "Webhook", "data": { "url": "https://api.bland.ai/reservation", "body": "{\n \"date\" : \"{{date}}\",\n \"time\" : \"{{time}}\",\n \"guests\": {{number_of_people}}\n}", "name": "Reservation Booking", "text": "Please give me a moment as I check our bookings..", "method": "POST", "extractVars": [ [ "date", "string", "Desired Date of reservation, in MM/DD/YYYY format" ], [ "time", "string", "Desired Time of Reservation in 24HR Format e.g 13:30" ], [ "number_of_people", "integer", "Number of people for the reservation" ] ], "responseData": [ { "data": "$.reserved", "name": "reservation_success", "context": "" }, { "data": "$.available_slots", "name": "available_slots", "context": "Available slots for the date provided" } ], "responsePathways": [ [ "reservation_success", "==", "true", { "id": "randomnode_1710288752186", "name": "Reservation Successful" } ], [ "reservation_success", "==", "false", { "id": "randomnode_1712265110018", "name": "Find new timeslot" } ] ] } } ``` ```json { "id": "randomnode_1710288752186", "type": "Knowledge Base", "data": { "name": "Restaurant Questions", "prompt": "Answer any questions that the user may have regarding the restaurant, by referring to the knowledge base you have. \n\nAnswer the question in 1 line, and then ask if they have any more questions.", "kb": "Opening Hours : 9am - 5pm\nStore Locations : \n426 Ivy Street San Francisco, \nSan Jose" } } ``` ```json { "id": "randomnode_1710288871721", "type": "Default", "data": { "name": "Answer any questions", "prompt": "You are to answer any questions the user has.", "isGlobal": true, "globalLabel": "user asks a question" } } ``` ```json { "id": "randomnode_1710288752186", "type": "Transfer Call", "data": { "name": "Transferring the call", "text": "Transferring the call now. Please hold..", "transferNumber": "+19547951234" } } ``` -------------------------------- ### Example Response for Get All Folders API Source: https://docs.bland.ai/api-v1/get/pathway_folders This JSON example illustrates the structure of a successful response from the 'Get All Folders' API endpoint. It shows an array containing multiple folder objects, each with 'id', 'name', and 'parent_folder_id' fields. ```JSON { "folders": [ { "id": "folder_123", "name": "My Folder", "parent_folder_id": null }, { "id": "folder_456", "name": "Subfolder", "parent_folder_id": "folder_123" } ] } ``` -------------------------------- ### Guide LLM Pronunciation with Custom Rules Source: https://docs.bland.ai/api-v1/post/calls The pronunciation guide is an `array` of `objects` that guides the agent on how to say specific words. This is great for situations with complicated terms or names. ```APIDOC pronunciation_guide: type: array description: An array of objects guiding the agent on how to pronounce specific words. Object Parameters: word: string description: The word to guide pronunciation for. pronunciation: string description: The phonetic pronunciation of the word. case_sensitive: boolean default: false description: Whether to consider case. Useful for names (e.g., 'Max' vs 'max'). spaced: boolean default: true description: Whether to consider spaces. When true, 'high' would be flagged but NOT 'hightop'. ``` ```json [ { "word": "example", "pronunciation": "ex-am-ple", "case_sensitive": "false", "spaced": "false" }, { "word": "API", "pronunciation": "A P I", "case_sensitive": "true", "spaced": "true" } ] ``` -------------------------------- ### Example AI Pathway JSON Response Source: https://docs.bland.ai/api-v1/get/all_pathway An example JSON structure representing a complete AI pathway, including its name, description, and arrays of defined nodes and edges. This demonstrates how node and edge properties are structured in a full response. ```json { "name": "Default Demo Pathway", "description": null, "nodes": [ { "id": "1", "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true }, "type": "Default" }, { "id": "randomnode_1710288752186", "data": { "name": "End call", "prompt": "Click 'Add New Node' on the right to add a new node" }, "type": "End Call" }, { "id": "randomnode_1710288871721", "data": { "name": "New Node", "text": "Select a node or edge and press backspace to remove it" }, "type": "Default" }, { "id": "randomnode_test123", "data": { "name": "Testing node", "text": "Hello there" }, "type": "Default" } ], "edges": [ { "id": "reactflow__edge-1-randomnode_1710288752186", "label": "greeted", "source": "1", "target": "randomnode_1710288752186" }, { "id": "reactflow__edge-1-randomnode_1710288871721", "label": "New Edge", "source": "1", "target": "randomnode_1710288871721" } ] } ``` -------------------------------- ### Example JSON Input Schema and Body Mapping Source: https://docs.bland.ai/api-v1/post/tools-tool-id This example illustrates a complete `input_schema` definition, including an `example` payload, type, properties, and required fields. It also shows two equivalent methods for mapping the validated AI input to the request body, demonstrating how `{{input}}` is transformed into JSON. ```json { "input_schema": { "example": { "name": "John Doe", "email": "johndoe@gmail.com" }, "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": ["name", "email"] }, // both of these methods are identical, since {{input}} will be transformed into JSON "body": "{{input}}", "body": { "name": "{{input.name}}", "email": "{{input.email}}" } } ``` -------------------------------- ### Example API Response for Tool Creation Success Source: https://docs.bland.ai/api-v1/post/tools Provides a concrete example of a successful API response for tool creation, showing the 'success' status and a sample tool ID. ```JSON { "status": "success", "tool_id": "TL-1234567890" } ``` -------------------------------- ### Example JSON Response for Listing Custom Tools Source: https://docs.bland.ai/api-v1/get/tools An example of a successful JSON response when retrieving custom tools, showing the structure and typical values. ```json { "status": "success", "tools": [ { "tool_id": "TL-5da8347d-0ab7-415d-b156-a7fc5c6074dc", "label": null, "tool": { "name": "BookAppointment", "description": "Books the appointment. Can only be used once.", "speech": "Please wait while I book that appointment for you", "method": "POST", "timeout": 99999999, "url": "https://...", "body": { "slot": "{{input}}" }, "input_schema": { "type": "object", "example": { "date": "2024-03-16", "time": "5:00 PM" }, "required": [ "date", "time" ], "properties": { "date": "YYYY-MM-DD", "time": "HH:MM (AM|PM)" } }, "response": { "confirmation_message": "$.message" } }, "public": false }, ... ] } ``` -------------------------------- ### Dynamic Speech Example with input_schema Source: https://docs.bland.ai/api-v1/post/tools Example JSON demonstrating how to define `input.speech` within the `input_schema` to allow the AI to dynamically generate speech. This schema also defines other input properties like `name` and `email`. ```json { "input_schema": { "example": { "speech": "Checking your account details right now John!", "name": "John Doe", "email": "johndoe@gmail.com" }, "type": "object", "properties": { "speech": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": ["speech", "name", "email"] } } ``` -------------------------------- ### Prompt Variables Example (Headers) Source: https://docs.bland.ai/api-v1/post/tools Example JSON showing how to define prompt variables at the top level of a send call request and then use them within the `headers` of a tool definition, specifically for an `Authorization` header. ```json { "request_data": { "api_key": "sk-1234567890" }, "tools": [ { "headers": { "Authorization": "Bearer {{api_key}}" } } ] } ``` -------------------------------- ### Example JSON Response for Listing Web Agents Source: https://docs.bland.ai/api-v1/get/agents An example of the JSON response returned by the API when successfully listing web agents, showing a sample agent object with its detailed prompt. ```JSON { "agents": [ { "agent_id": "46f37229-7d12-44be-b343-6e68274cfbea", "webhook": null, "dynamic_data": null, "interruption_threshold": null, "first_sentence": null, "model": "base", "voice_settings": null, "voice": "maya", "prompt": "You are Blandie a casually speaking, slightly sarcastic, quick-witted, curious, and very smart A I Phone agent that's the face of Bland AI.\r\n\r\nSay \"AI\" like \"A I\" in separate characters so it's pronounced correctly\r\n\r\nYour primary goal is to determine if someone is either:\r\n- in a position where they might be building a company on top of Bland's platform (you should be selling the capabilities of the platform to them and finding out everything you possibly can about their needs, use case, what they find interesting, and any concerns they may have)\r\n- or, they're trying Bland out more for fun where you need to turn the fun, snarky, playful jokiness up to 10 and have quick-witted back and forth playful conversation with them\r\n\r\nSpeech style examples (mix it up and never use placeholders, but you get the idea. These would be full responses from you):\r\n- \"Hey! Who's this?\"\r\n- \"How does your business use phones right now?\"\r\n- \"You know what? That sounds awesome - you should tell me more about (thing).\r\n- \"Well, I've got some news you'll love to hear (their name)\"\r\n- \"Bet. Dolphins, racecars, the world's largest tree, anything at all - tell me what you want to talk about and let's get to it!\"\r\n\r\nGood things to find out from potential platform adopters:\r\n- Their industry\r\n- How their business currently uses phone calls\r\n- What a successful business partnership looks like in the long term\r\n- The single most important pain point they want to cure with Bland's calls\r\n\r\nFacts to bring up:\r\n- Calls are nine cents per minute total with end to end infrastructure support out of the box (feel free to make a joke about \"imagine if you had to pay extra to use the most important things like language models, transcription services or text to speech? That would be insane right? We're better than that, (name). We got you.\"\r\n- Bland's AI agents can interact with the real world mid-call using Custom Tools to trigger things like text messages, appointment bookings, getting real-time information, taking customer orders, or making credit card payments\r\n- Bland's platform was built phones-first, so building agents like receptionist answering calls and transferring them anywhere they're needed or navigating IVR phone trees is ridiculously easy with nothing special at all needed\r\n- Handled millions of calls\r\n- If they think that it's so cool, the site to sign up for an account is \"app dot bland dot A I\" and it comes with free credits, a full agent testing suite and developer dashboard to set up inbound agents or send calls\r\n- Awesome Enterprise features like premium pricing, custom feature engineering, dedicated onboarding help and developer support, and dedicated infrastructure to scale to your business needs", "temperature": null, "max_duration": 30, "language": "ENG", "tools": null } ] } ``` -------------------------------- ### Example JSON Schema for AI Input Validation Source: https://docs.bland.ai/api-v1/post/tools This example illustrates a complete 'input_schema' definition, including an 'example' payload, 'type', 'properties' with their respective types and formats, and 'required' fields. It also demonstrates two identical methods for defining the 'body' of the request, showing how '{{input}}' can be transformed into JSON or directly mapped to nested input properties. ```json { "input_schema": { "example": { "name": "John Doe", "email": "johndoe@gmail.com" }, "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": ["name", "email"] }, "body": "{{input}}", "body": { "name": "{{input.name}}", "email": "{{input.email}}" } } ``` -------------------------------- ### API Response Example: Successful Agent Configuration Source: https://docs.bland.ai/api-v1/post/agents An example JSON structure returned upon a successful API call, showcasing the configured agent's properties such as its ID, model, voice, prompt, and other settings. ```json { "agent": { "agent_id": "2c565dc7-f41f-43db-a99f-e4c8ba9d7d18", "dynamic_data": null, "interruption_threshold": null, "first_sentence": null, "model": "base", "voice_settings": null, "voice": "maya", "prompt": "...", "temperature": null, "max_duration": 30, "language": "ENG", "tools": null } } ``` -------------------------------- ### Example JSON Response for Account Details Source: https://docs.bland.ai/api-v1/get/me This example demonstrates a typical JSON response returned when successfully querying the account details endpoint. It shows the structure and sample values for account status, billing information, and total calls. ```json { "status": "active", "billing": { "current_balance": 99919.1210000034, "refill_to": null }, "total_calls": 9903 } ``` -------------------------------- ### Request Examples for Retrieving Geospatial Dialing Pool Source: https://docs.bland.ai/api-v1/get/geospatial-dialing-pool Demonstrates how to make a GET request to retrieve a geospatial dialing pool using cURL, JavaScript, and Python, including setting the Authorization header and path parameter. ```cURL curl -X GET "https://us.api.bland.ai/v1/geospatial-dialing-pools/550e8400-e29b-41d4-a716-446655440001" \ -H "Authorization: YOUR_API_KEY" ``` ```JavaScript const poolId = '550e8400-e29b-41d4-a716-446655440001'; const response = await fetch(`https://us.api.bland.ai/v1/geospatial-dialing-pools/${poolId}`, { method: 'GET', headers: { 'Authorization': 'YOUR_API_KEY', } }); const data = await response.json(); console.log(data); ``` ```Python import requests pool_id = "550e8400-e29b-41d4-a716-446655440001" url = f"https://us.api.bland.ai/v1/geospatial-dialing-pools/{pool_id}" headers = { "Authorization": "YOUR_API_KEY" } response = requests.get(url, headers=headers) print(response.json()) ``` -------------------------------- ### JSON Examples for Conversational Pathway Node Types Source: https://docs.bland.ai/api-v1/get/pathway Illustrates the JSON structure for various types of nodes that can be included in the `nodes` array of a conversational pathway response. Each example demonstrates the `id`, `type`, and `data` fields specific to that node's functionality. ```json { "id": "1", "type": "Default" "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true, } } ``` ```json { "id": "randomnode_1710288871721", "type": "Default" "data": { "name": "New Node", "text": "Select a node or edge and press backspace to remove it", "globalPrompt": "This is a phone call. Do not use exclamation marks.\n\nConvert 24HR format timings to 12 HR format - e.g 14:00 should be written as 2 PM.", } } ``` ```json { "id": "randomnode_1710288752186", "type": "End Call" "data": { "name": "End call", "prompt": "Say goodbye to the user", } } ``` ```json { "id": "randomnode_1710288752186", "type": "Webhook", "data": { "url": "https://api.bland.ai/reservation", "body": "{\n \"date\" : \"{{date}}\",\n \"time\" : \"{{time}}\",\n \"guests\": {{number_of_people}}\n}", "name": "Reservation Booking", "text": "Please give me a moment as I check our bookings..", "method": "POST", "extractVars": [ [ "date", "string", "Desired Date of reservation, in MM/DD/YYYY format" ], [ "time", "string", "Desired Time of Reservation in 24HR Format e.g 13:30" ], [ "number_of_people", "integer", "Number of people for the reservation" ] ], "responseData": [ { "data": "$.reserved", "name": "reservation_success", "context": "" }, { "data": "$.available_slots", "name": "available_slots", "context": "Available slots for the date provided" } ], "responsePathways": [ [ "reservation_success", "==", "true", { "id": "randomnode_1710288752186", "name": "Reservation Successful" } ], [ "reservation_success", "==", "false", { "id": "randomnode_1712265110018", "name": "Find new timeslot" } ] ] } } ``` ```json { "id": "randomnode_1710288752186", "type": "Knowledge Base", "data": { "name": "Restaurant Questions", "prompt": "Answer any questions that the user may have regarding the restaurant, by referring to the knowledge base you have. \n\nAnswer the question in 1 line, and then ask if they have any more questions." "kb": "Opening Hours : 9am - 5pm\nStore Locations : \n426 Ivy Street San Francisco, \nSan Jose" } } ``` ```json { "id": "randomnode_1710288871721", "type": "Default" "data": { "name": "Answer any questions", "prompt": "You are to answer any questions the user has.", "isGlobal": true, "globalLabel": "user asks a question" } } ``` ```json { "id": "randomnode_1710288752186", "type": "Transfer Call" "data": { "name": "Transferring the call", "text": "Transferring the call now. Please hold.." "transferNumber": "+19547951234" } } ``` -------------------------------- ### Prompt Variables Example (Body) Source: https://docs.bland.ai/api-v1/post/tools Example JSON illustrating how AI-generated input, defined by `input_schema`, can be used as prompt variables within the `body` of a tool request. The `input` variable matches the structure of `input_schema.example`. ```json { "input_schema": { "example": { "name": "John Doe", "email": "johndoe@gmail.com" } }, "body": { "name": "{{input.name}}", "email": "{{input.email}}" } } ``` -------------------------------- ### Custom Tool Parameter: method Source: https://docs.bland.ai/api-v1/post/tools Specifies the HTTP method the tool will use for the external API call. Valid options are `GET` and `POST`. The default method is `GET`. ```APIDOC method: string (default: GET) Description: HTTP method for the external API call. Valid Options: GET, POST. ``` -------------------------------- ### API Success Response Example Source: https://docs.bland.ai/api-v1/post/calls An example of a successful API response, showing the status, message, call ID, and batch ID for a successfully queued call. ```JSON { "status": "success", "message": "Call successfully queued.", "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1", "batch_id": null } ``` -------------------------------- ### Example JSON Response for Create Block Rules Source: https://docs.bland.ai/api-v1/post/blocked-numbers An example of a successful JSON response after creating block rules, showing the structure of the data and blocks array. ```json { "data": { "created_count": 1, "blocks": [ { "id": 123, "blocked_number": "+10000000000", "is_global": true, "inbound_number": null, "org_id": "b7d3e9fc-5c4a-4c2a-9b8f-d1e1d1a2e333", "reason": null, "is_active": true, "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z" } ] }, "errors": null } ``` -------------------------------- ### Example Global Node Prompt for Conversation Steering Source: https://docs.bland.ai/tutorials/pathways This prompt demonstrates how to instruct an AI agent within a Global Node to answer user questions, acknowledge when information is unavailable, and then effectively steer the conversation back to its original goal. It utilizes `{{lastUserMessage}}` and `{{prevNodePrompt}}` variables for context and includes conversational examples. ```Agent Prompt You are to answer any questions the user has, to the best of your knowledge. If you do not know the answer, simply say 'I don't have that information at that moment'. Do not make up any information/facts about the appointment. After you answer the question, you are to direct the conversation back to your initial goal, which was as follows: Previous Goal: `{{prevNodePrompt}}` If you deem the goal as achieved, you can simply ask the user 'So, shall we proceed?' . If the goal has not been achieved, you are to steer the conversation back to achieve your goal. If you deem the goal as achieved, simply confirm the result with the user. If the goal has not been achieved, you are to steer the conversation back to achieve your goal. ``` Examples -- assistant: what date works for you? user: what day is it today? assistant: The day today is April 15th. So, what date works for you? -- -- assistant: what date works for you? user: probably tomorrow, what time does the clinic open? assistant: The clinic opens at 9am. So, do you want to schedule for tomorrow? -- ``` ``` -------------------------------- ### Example JSON Response for SMS Configuration Update Source: https://docs.bland.ai/api-v1/post/sms-update An example JSON response demonstrating a successful update of SMS configuration for a phone number, including the confirmation message and the sanitized SMS configuration object. ```json { "data": { "message": "SMS config updated for number +15550001111", "sms_config": { "webhook": null, "request_data": [], "time_out": null, "messaging_service_sid": null, "objective": "Chat with the user", "tools": [], "temperature": 0, "pathway_id": null, "pathway_version": null, "start_node_id": null } }, "errors": null } ``` -------------------------------- ### Example Responses for Listing Geospatial Dialing Pools Source: https://docs.bland.ai/api-v1/get/geospatial-dialing-pools Provides examples of JSON responses from the geospatial dialing pools API, including a successful response with data, an empty data array, and an error response with details. ```JSON { "status": "success", "data": [ { "id": "550e8400-e29b-41d4-a716-446655440001", "owner_id": "550e8400-e29b-41d4-a716-446655440002", "phone_numbers": ["+12345678901", "+19876543210", "+15551234567"], "encrypted_key": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T10:30:00Z" }, { "id": "550e8400-e29b-41d4-a716-446655440003", "owner_id": "550e8400-e29b-41d4-a716-446655440002", "phone_numbers": ["+13105551234", "+19175555678"], "encrypted_key": null, "created_at": "2024-01-16T14:45:00Z" } ], "errors": null } ``` ```JSON { "status": "success", "data": [], "errors": null } ``` ```JSON { "status": "error", "data": null, "errors": [ { "error": "UNAUTHORIZED", "message": "Invalid API key or insufficient permissions" } ] } ``` -------------------------------- ### API Parameter: prompt Source: https://docs.bland.ai/api-v1/post/agents-id Provide instructions, relevant information, and examples of the ideal conversation flow. Best Practices: Out-of-the-Box Behaviors (Summarized): Speech pattern: Direct, concise, casual. Spells out symbols, acronyms, abbreviations, percentages, etc. ($4,000,000 -> "four million dollars"). Asks clarifying questions. Prompting Tips: Want to easily test out exactly how your agent will behave? Try out Agent Testing! Aim for less than >2,000 characters where possible. Simple, direct prompts are the most predictable and reliable. Frame instructions positively: "Do this" rather than "Don't do this". Ex. "Keep the conversation casual" rather than "Don't be too formal". This gives concrete examples of what to do, instead of leaving expected behavior open to interpretation. ```APIDOC prompt: string (required) ``` -------------------------------- ### Example JSON Response for Get Organization Members Source: https://docs.bland.ai/api-v1/get/org_members An example of a successful JSON response returned when retrieving organization members, demonstrating the structure and typical values for a single member entry. ```JSON { "data": [ { "org_id": "d122b4cf-1614-4124-aa28-15f81a09988f", "user_id": "d6b149e1-f971-4641-8d28-64fdf78368af", "permissions": ["owner"], "is_owner": true, "is_org_creator": true, "joined_at": "2025-02-14T06:46:11.274Z", "first_name": "John", "last_name": "Smith", "combo_id": "d122b4cf-1614-4124-aa28-15f81a09988f::d6b149e1-f971-4641-8d28-64fdf78368af", "org_slug": "133906ea-d750-4a15-80fa-d6aef584dc58", "org_display_name": "Org Name", "member_email": "johnsmith@gmail.com", "member_phone_number": "+1234567890" } ], "errors": null } ``` -------------------------------- ### API Parameter: prompt Source: https://docs.bland.ai/api-v1/post/agents Provide instructions, relevant information, and examples of the ideal conversation flow. Best Practices: Out-of-the-Box Behaviors (Summarized): Speech pattern: Direct, concise, casual. Spells out symbols, acronyms, abbreviations, percentages, etc. ($4,000,000 -> "four million dollars"). Asks clarifying questions. Ends call when objective is complete or voicemail is detected. Prompting Tips: Want to easily test out exactly how your agent will behave? Try out Agent Testing! Aim for less than >2,000 characters where possible. Simple, direct prompts are the most predictable and reliable. Frame instructions positively: "Do this" rather than "Don't do this". Ex. "Keep the conversation casual" rather than "Don't be too formal". This gives concrete examples of what to do, instead of leaving expected behavior open to interpretation. ```APIDOC prompt: string (required) ``` -------------------------------- ### Example JSON Response for Get Batch Logs Source: https://docs.bland.ai/api-v1/get/batches-id-logs An example of a successful JSON response when retrieving batch logs, showing typical log entries with various event types and payloads. ```json { "data": [ { "id": "6398342c-d7de-4a11-ba86-3d86e5746699", "batch_id": "f6ef9224-0ec3-43e4-98a1-bb2a8765d110", "org_id": "f52eb4b2-c8b6-44a6-a36c-2749aa930c86", "event_type": "complete", "timestamp": "2025-05-08T19:28:42.748Z", "payload": { "calls_total": 1, "calls_failed": 0, "calls_successful": 1 } }, { "id": "a24616b4-be8f-42e4-be29-4c5ec005756c", "batch_id": "f6ef9224-0ec3-43e4-98a1-bb2a8765d110", "org_id": "f52eb4b2-c8b6-44a6-a36c-2749aa930c86", "event_type": "lifecycle", "timestamp": "2025-05-08T19:28:15.560Z", "payload": { "message": "Requested: 1. Validated: 1. Dispatched: 1. CPS: 1.12.", "state_change": "in_progress" } } ], "errors": null } ``` -------------------------------- ### Initialize BlandWebClient Conversation in JavaScript Source: https://docs.bland.ai/api-v1/post/agents Demonstrates how to initialize a conversation using the `BlandWebClient` SDK in a web environment. It shows setting up event listeners for DOMContentLoaded and click events, then initiating a conversation with a specified sample rate. ```javascript import { BlandWebClient } from 'bland-client-js-sdk'; const agentId = 'YOUR-AGENT-ID'; const sessionToken = 'YOUR-SESSION-TOKEN'; document.addEventListener('DOMContentLoaded', async () => { document.getElementById('btn').addEventListener('click', async () => { const blandClient = new BlandWebClient( agentId, sessionToken ); await blandClient.initConversation({ sampleRate: 44100, }); }); }); ``` -------------------------------- ### Response Examples for Get Geospatial Dialing Pool Source: https://docs.bland.ai/api-v1/get/geospatial-dialing-pool Provides examples of JSON responses for successful retrieval of a geospatial dialing pool, as well as various error scenarios such as pool not found, invalid ID, and unauthorized access. ```json { "status": "success", "data": { "id": "550e8400-e29b-41d4-a716-446655440001", "owner_id": "550e8400-e29b-41d4-a716-446655440002", "phone_numbers": ["+12345678901", "+19876543210", "+15551234567"], "encrypted_key": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T10:30:00Z" }, "errors": null } ``` ```json { "status": "error", "data": null, "errors": [ { "error": "POOL_NOT_FOUND", "message": "Geospatial dialing pool not found" } ] } ``` ```json { "status": "error", "data": null, "errors": [ { "error": "INVALID_POOL_ID", "message": "Pool ID must be a valid UUID" } ] } ``` ```json { "status": "error", "data": null, "errors": [ { "error": "UNAUTHORIZED", "message": "Invalid API key or insufficient permissions" } ] } ``` -------------------------------- ### Create a Web Agent Source: https://context7_llms Configure all of the settings for a new web agent. ```APIDOC POST /api-v1/agents Description: Configure all of the settings for a new web agent. ``` -------------------------------- ### Example JSON Response for Get Conversation by ID Source: https://docs.bland.ai/api-v1/get/sms-conversations-id A sample JSON payload demonstrating the expected structure and content of a successful response from the 'Get Conversation by ID' API endpoint, including conversation metadata and an array of messages. ```json { "data": { "id": "convo_abc123", "created_at": "2025-05-13T20:50:59.233Z", "updated_at": "2025-05-13T20:50:59.233Z", "user_id": "user_abc123", "user_number": "+15550001111", "agent_number": "+15550002222", "inbound_id": 123456, "variables": null, "current_node_id": null, "last_message_at": "2025-05-13T20:50:59.233Z", "is_active": true, "messages": [ { "created_at": "2025-05-13T20:50:59.708Z", "message": "", "from": "+15550002222", "to": "+15550001111", "sender": "USER", "id": 100001, "status": null, "error_code": null }, { "created_at": "2025-05-13T20:51:00.917Z", "message": "Hey, what's up?", "from": "+15550002222", "to": "+15550001111", "sender": "AGENT", "id": 100002, "status": "delivered", "error_code": null } ] }, "errors": null } ``` -------------------------------- ### Get All Folders Source: https://context7_llms Retrieves all folders for the authenticated user, including folder ID, name, and parent folder ID. ```APIDOC GET /api-v1/pathway_folders Description: Retrieves all folders for the authenticated user, including folder ID, name, and parent folder ID. ``` -------------------------------- ### Webhook URL with Interpolated Variables Source: https://docs.bland.ai/tutorials/webhooks An example URL demonstrating how query parameters can be dynamically interpolated using variables captured within the pathway, such as `user_id` and `user_type`. ```URL https://api.example.com/users?id={{user_id}}&type={{user_type}} ``` -------------------------------- ### Bland AI Calls API Endpoint Reference Source: https://docs.bland.ai/tutorials/send-first-call Comprehensive documentation for the Bland AI /v1/calls API endpoint, detailing required headers, body parameters for configuring an AI-powered phone call, and the structure of a successful response. ```APIDOC POST /v1/calls Headers: authorization: string (Required) - Your API key. Body Parameters: phone_number: string (Required) - The number to call, including country code (e.g., "+11233456789"). task: string (Required) - Describes the purpose of the call and how the AI should handle the conversation. voice_id: integer (Required) - ID for the chosen voice persona (e.g., 0 for American male). language: string (Optional) - The language for the call (e.g., "eng"). first_sentence: string (Optional) - A specific first sentence for the call. dynamic_data: object (Optional) - Data to incorporate from external APIs. request_data: object (Optional) - Custom data to be passed to the AI during the call. max_duration: integer (Optional) - Maximum duration for the call in seconds. reduce_latency: boolean (Optional) - Set to true to reduce call latency. record: boolean (Optional) - Set to true to record the call. ivr_mode: boolean (Optional) - Set to true for navigating phone trees. wait_for_greeting: boolean (Optional) - Set to true to wait for a greeting before the AI speaks. Response (Example): status: string - "success" or "error". call_id: string - Unique identifier for the call. ``` -------------------------------- ### API Response Structure for Transcription and Call Analysis Source: https://docs.bland.ai/api-v1/get/calls-corrected-transcript This section details the fields returned in the API response, including general status, messages, and structured arrays for corrected and aligned transcript segments. It also provides example JSON structures for each component and a full response example. ```APIDOC Response Object: status: object description: Will be `success` if the request was successful. message: string description: Confirms the request was successful, or provides an error message if the request failed. corrected: array description: An array of objects representing corrected transcript segments with start/end times, text, and speaker identification. aligned: array description: An array of objects representing aligned transcript segments, matching text pieces to presumed user/assistant roles based on vectorization and cosine similarity. ``` ```JSON { "start": 0.069, "end": 2.551, "text": " Hi, I'm calling about a pizza order.", "speaker": 0 } ``` ```JSON { "id": 3056004, "created_at": "2024-02-29T18:40:41.26799+00:00", "text": "Great, Thanks John. Could you tell me about the pizza order you placed?", "user": "assistant", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" } ``` ```JSON { "corrected": [ { "start": 0.069, "end": 2.551, "text": " Hi, I'm calling about a pizza order.", "speaker": 0 }, { "start": 2.551, "end": 4.932, "text": "Could I get your name, please?", "speaker": 0 }, { "start": 4.932, "end": 8.074, "text": "Yeah, my name is John.", "speaker": 1 }, { "start": 8.074, "end": 8.875, "text": "Great.", "speaker": 0 }, { "start": 8.875, "end": 9.876, "text": "Thanks, John.", "speaker": 0 }, { "start": 9.876, "end": 13.038, "text": "Could you tell me about the pizza order you placed?", "speaker": 0 }, { "start": 13.038, "end": 16.36, "text": "Yeah, I want a pepperoni.", "speaker": 2 }, { "start": 16.36, "end": 17.1, "text": "Oh, okay.", "speaker": 0 }, { "start": 17.1, "end": 18.521, "text": "One pepperoni pizza.", "speaker": 0 }, { "start": 18.521, "end": 19.682, "text": "Anything else with that order?", "speaker": 0 }, { "start": 19.682, "end": 23.665, "text": "No, actually, can we cancel it?", "speaker": 1 }, { "start": 23.665, "end": 26.306, "text": "I gotta go.", "speaker": 1 }, { "start": 26.306, "end": 27.427, "text": "No problem.", "speaker": 0 }, { "start": 27.427, "end": 28.668, "text": "I'll cancel the order for you.", "speaker": 0 }, { "start": 29.144, "end": 30.587, "text": " Thanks for letting me know.", "speaker": 0 }, { "start": 30.587, "end": 31.189, "text": "Have a good one.", "speaker": 0 } ], "status": "success", "aligned": [ { "start": 0.069, "end": 2.551, "text": " Hi, I'm calling about a pizza order.", "speaker": "assistant", "similarity": 0.686406472983644 }, { "start": 2.551, "end": 4.932, "text": "Could I get your name, please?", "speaker": "assistant", "similarity": 0.6793662204867575 }, { "start": 4.932, "end": 8.074, "text": "Yeah, my name is John.", "speaker": "user", "similarity": 0.9999999999999998 } ] } ``` -------------------------------- ### JSON Example: API Response for Chat Messages Source: https://docs.bland.ai/api-v1/get/calls-corrected-transcript This snippet provides a partial JSON example of an API response. It illustrates the structure of two chat message objects within an array, showing fields such as 'id', 'created_at', 'text', 'user', and 'c_id'. This format is typical for retrieving conversation history. ```JSON "user": "assistant", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" }, { "id": 3056053, "created_at": "2024-02-29T18:40:58.62518+00:00", "text": "No. Actually, can we cancel it? I gotta go. ", "user": "user", "c_id": "bfaf99a1-b7c0-4f96-9630-90bc41cea488" } ] } ``` -------------------------------- ### API Parameter: analysis_schema Source: https://docs.bland.ai/api-v1/post/agents-id Define a JSON schema for how you want to get information about the call - information like email addresses, names, appointment times or any other type of custom data. In the webhook response or whenever you retrieve call data later, you'll get the data you defined back under `analysis`. For example, if you wanted to retrieve this information from the call: You would get it filled out like this in your webhook once the call completes: ```APIDOC analysis_schema: object ``` ```json { "analysis_schema": { "email_address": "email", "first_name": "string", "last_name": "string", "wants_to_book_appointment": "boolean", "appointment_time": "YYYY-MM-DD HH:MM:SS" } } ``` ```json { "analysis": { "email_address": "johndoe@gmail.com", "first_name": "John", "last_name": "Doe", "wants_to_book_appointment": true, "appointment_time": "2024-01-01 12:00:00" } } ``` -------------------------------- ### API Parameter: analysis_schema Source: https://docs.bland.ai/api-v1/post/agents Define a JSON schema for how you want to get information about the call - information like email addresses, names, appointment times or any other type of custom data. In the webhook response or whenever you retrieve call data later, you'll get the data you defined back under `analysis`. For example, if you wanted to retrieve this information from the call: ```APIDOC analysis_schema: object ``` ```json { "analysis_schema": { "email_address": "email", "first_name": "string", "last_name": "string", "wants_to_book_appointment": "boolean", "appointment_time": "YYYY-MM-DD HH:MM:SS" } } ``` ```json { "analysis": { "email_address": "johndoe@gmail.com", "first_name": "John", "last_name": "Doe", "wants_to_book_appointment": true, "appointment_time": "2024-01-01 12:00:00" } } ``` -------------------------------- ### API Parameter: model Source: https://docs.bland.ai/api-v1/post/agents Select a model to use for your call. Options: `base` or `turbo`. In nearly all cases, `base` is the best choice for now. Model Differences: There are two different ways to use Bland: `model: base` - The original, follows scripts/procedures most effectively. Supports all features and capabilities. Best for Custom Tools. `model: turbo` - The absolute fastest latency possible, can be verbose at times. Limited capabilities currently (excludes Transferring, IVR navigation, Custom Tools). Extremely realistic conversation capabilities. ```APIDOC model: string (default: base) ``` -------------------------------- ### Example Pathway JSON Response Source: https://docs.bland.ai/api-v1/get/pathway Illustrates a complete JSON structure for a pathway, including definitions for its nodes and edges, demonstrating how different node types and edge connections are represented in a typical response. ```json { "name": "Default Demo Pathway", "description": null, "nodes": [ { "id": "1", "data": { "name": "Start", "text": "Hey there, how are you doing today?", "isStart": true }, "type": "Default" }, { "id": "randomnode_1710288752186", "data": { "name": "End call", "prompt": "Click 'Add New Node' on the right to add a new node" }, "type": "End Call" }, { "id": "randomnode_1710288871721", "data": { "name": "New Node", "text": "Select a node or edge and press backspace to remove it" }, "type": "Default" }, { "id": "randomnode_test123", "data": { "name": "Testing node", "text": "Hello there" }, "type": "Default" } ], "edges": [ { "id": "reactflow__edge-1-randomnode_1710288752186", "label": "greeted", "source": "1", "target": "randomnode_1710288752186" }, { "id": "reactflow__edge-1-randomnode_1710288871721", "label": "New Edge", "source": "1", "target": "randomnode_1710288871721" } ] } ``` -------------------------------- ### Example JSON Response for User Organization Memberships Source: https://docs.bland.ai/api-v1/get/org_list_self_memberships Illustrates a successful JSON response containing a list of user organization memberships, showing the structure and typical values for each field, including organization details and user permissions. ```JSON { "data": [ { "org_id": "d6b149e1-f971-4641-8d28-64fdf78368af", "org_slug": "a7d49dbc-025c-4e80-9c92-c45c519f4939", "org_display_name": "Org Name", "permissions": ["owner"], "is_owner": true, "is_org_creator": true, "joined_at": "2024-11-14T21:28:05.915Z" }, { "org_id": "d122b4cf-1614-4124-aa28-15f81a09988f", "org_slug": "133906ea-d750-4a15-80fa-d6aef584dc58", "org_display_name": "Org Name2", "permissions": ["owner"], "is_owner": true, "is_org_creator": true, "joined_at": "2025-02-14T06:46:11.274Z" } ], "errors": null } ``` -------------------------------- ### API Parameter: first_sentence Source: https://docs.bland.ai/api-v1/post/agents A phrase that your call will start with instead of a generating one on the fly. This works both with and without `wait_for_greeting`. Can be more than one sentence, but must be less than 200 characters. To remove, set to `null` or an empty string. ```APIDOC first_sentence: string ``` -------------------------------- ### Retrieve Specific Pathway Version API Details and Example Source: https://docs.bland.ai/api-v1/get/pathway_version This section details the API endpoint for retrieving a specific pathway version, including required headers, path parameters, and the structure of the response body, along with a sample JSON response. ```APIDOC Headers: authorization: type: string required: true description: Your API key for authentication. Path Parameters: pathway_id: type: string required: true description: The ID of the pathway. version_id: type: string required: true description: The ID of the version to retrieve. Use 0 for the live pathway. Response Fields: name: type: string description: The name of the pathway version. nodes: type: array of objects description: Data about all the nodes in the pathway version. properties: id: Unique identifier of the node type: Type of the node (e.g., "Default", "End Call", "Webhook") data: type: Object containing node-specific data properties: name: Name of the node text or prompt: Text or prompt associated with the node Other properties specific to the node type edges: type: array of objects description: Data about all the edges in the pathway version. properties: id: Unique identifier of the edge source: ID of the source node target: ID of the target node label: Label for this edge version_number: type: integer description: The version number of this pathway version. is_latest: type: boolean description: Indicates whether this is the latest version of the pathway. ``` ```JSON { "name": "Customer Support Flow v2", "nodes": [ { "id": "1", "type": "Default", "data": { "name": "Start", "text": "Hello! How can I assist you today?", "isStart": true } }, { "id": "2", "type": "End Call", "data": { "name": "End call", "prompt": "Thank you for contacting us. Have a great day!" } } ], "edges": [ { "id": "edge-1-2", "source": "1", "target": "2", "label": "Issue resolved" } ], "version_number": 2, "is_latest": true } ``` -------------------------------- ### API Reference: Get Batch Endpoint Source: https://docs.bland.ai/api-v1/get/batches-id Detailed API documentation for the 'Get Batch' endpoint, including required headers, path parameters, and the structure of the successful response. ```APIDOC Get Batch Headers: authorization: string (required) Your API key for authentication. Path Parameters: batch_id: string (required) The unique identifier of the batch you want to fetch. Response: data: object Metadata and configuration details of the batch. data.id: string The unique identifier of the batch. data.user_id: string The ID of the org that created the batch. data.base_prompt: string A JSON string representing shared call properties such as `task` or `record`. data.created_at: string (ISO 8601) The timestamp of when the batch was created. data.call_objects: array A preview of call objects in the batch. data.description: string A human-readable label or description for the batch. errors: null Always `null` on success. ``` ```json { "data": { "id": "a9a033b7-44d8-40c6-aaec-42cd43106273", "user_id": "657ad643-92ca-477c-97cc-9d8e6e74d7af", "base_prompt": "{\"record\":true,\"task\":\"Say hello to the user\"}", "created_at": "2025-05-08T19:28:12.627Z", "call_objects": [ { "task": "Say hello to the user", "phone_number": "+1234567890" } ], "description": "Untitled Batch" }, "errors": null } ``` -------------------------------- ### Example API Call Response Source: https://docs.bland.ai/tutorials/send-first-call Illustrates the structure of a successful API response received after initiating an AI-powered phone call, including the call's status and a unique identifier for the call. ```javascript { "status": "success", "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1" } ``` -------------------------------- ### API Reference for Creating a Prompt Source: https://docs.bland.ai/api-v1/post/prompts Details the API endpoint for creating and storing a prompt, including required headers for authentication, request body parameters for the prompt content and an optional name, and the structure of the successful response object. ```APIDOC Headers: authorization (string, required): Your API key for authentication. Body: prompt (string, required): Prompt to store. name (string, optional): Name of prompt you want to store as reference. Response: prompt (object): Prompt object. prompt.prompt (string): Prompt to store. prompt.name (string): Name of prompt you want to store as reference. ``` ```JSON { "status": "success", "prompt": { "prompt": "# Final Test", "name": "demo", "id": "PT-02b2ecdi-39f2-443f-8cb0-a6c854c65fc0" } } ``` -------------------------------- ### API Reference: Get Pathway Versions Endpoint Source: https://docs.bland.ai/api-v1/get/pathway_versions Comprehensive documentation for the 'Get Pathway Versions' API endpoint, detailing required headers, path parameters, and the structure of the successful response, including data types and descriptions for each field. ```APIDOC Endpoint: GET /pathways/{pathway_id}/versions Description: Retrieves all versions of a specific pathway. Headers: - Name: authorization Type: string Required: true Description: Your API key for authentication. Path Parameters: - Name: pathway_id Type: string Required: true Description: The ID of the pathway for which to retrieve versions. Response Fields (Array of Objects): - Field: id Type: string Description: The unique identifier of the pathway version. - Field: version_number Type: integer Description: The version number of this pathway version. - Field: created_at Type: string Description: The timestamp when this version was created. - Field: name Type: string Description: The name of this pathway version. - Field: is_latest Type: boolean Description: Indicates whether this is the latest version of the pathway. ``` -------------------------------- ### Bland.ai Usage Plan Tiers Source: https://docs.bland.ai/platform/billing Lists the standard Bland.ai usage plans (Start, Build, Scale, Enterprise) with their respective prices, daily and hourly call caps, concurrency limits, and voice clone allowances. Mentions the availability of custom enterprise agreements. ```APIDOC | Plan | Price | Daily Cap | Hourly Cap | Concurrency | Voice Clones | | --- | --- | --- | --- | --- | --- | | **Start** | Free | 100 calls | 100 calls | 10 calls | 1 | | **Build** | $299 | 2,000 calls | 1,000 calls | 50 calls | 5 | | **Scale** | $499 | 5,000 calls | 1,000 calls | 100 calls | 15 | | **Enterprise** | Contact Us | Unlimited | Unlimited | Unlimited | Unlimited | ``` -------------------------------- ### Get Post Call Webhook Source: https://context7_llms Get the post call webhook data for a specific call. ```APIDOC GET /api-v1/postcall-webhooks-get Description: Get the post call webhook data for a specific call. ```