I’m integrating an API into my project and need guidance on defining the request/response structure and field mapping in VAPI. I am retrieving available appointment slots from an external API. I have the API code ready, but I need to understand: How and where can I define the structure of the request and response payload, that vapi can handle this data? How can I map specific response fields / variables for use in the conversation? https://cdn.discordapp.com/attachments/1348369676618567721/1348369677067489341/message.txt?ex=67cf369e&is=67cde51e&hm=1d6a6524795b0604bd4c5d83cdcd436775ebd39e1b6d064f290712583c6237c5&

## Defining Request/Response Structure in VAPI To integrate your appointment slots API with VAPI, you'll need to create a custom function tool. Here's how to define the structure for your API: ### 1. Create a Custom Function Tool In VAPI, you can define the request/response structure by creating a custom function tool with the following components: 1. **Tool Type**: Use

FUNCTION_TOOL

as your tool type 2. **Function Definition**: Define the JSON schema for your API using OpenAIFunction structure Here's how you would define your appointment slots tool:

json
{
  "type": "function",
  "async": false,
  "function": {
    "name": "get_available_appointment_slots",
    "description": "Retrieves a list of available appointment slots from the calendar",
    "parameters": {
      "type": "object",
      "properties": {
        "start_date": {
          "type": "string",
          "description": "Start date for appointment search in YYYY-MM-DD format"
        },
        "end_date": {
          "type": "string",
          "description": "End date for appointment search in YYYY-MM-DD format"
        },
        "timezone": {
          "type": "string",
          "description": "Timezone for the appointment search (e.g., Europe/Berlin)",
          "default": "Europe/Berlin"
        }
      },
      "required": ["start_date", "end_date"]
    }
  },
  "server": {
    "url": "https://your-api-endpoint.com/get-slots",
    "method": "POST"
  },
  "messages": [
    {
      "type": "request-start",
      "message": "Let me check the available appointment slots for you."
    },
    {
      "type": "request-complete",
      "message": "I've found several available appointment slots."
    },
    {
      "type": "request-failed",
      "message": "I'm sorry, I couldn't retrieve the appointment slots at this time."
    }
  ]
}

### 2. Response Structure For handling the response from your API, VAPI will automatically process the JSON response data. Your API should return a response in the format similar to the example you provided:

json
{
  "results": [
    {
      "toolCallId": "call_test123456",
      "result": "I've found several available appointment slots."
    }
  ]
}

## Implementation Steps 1. **Create the Tool in VAPI Dashboard**: - Go to the Tools section - Create a new custom tool (Function Tool) - Define the schema based on the examples above - Set your API endpoint URL in the server configuration 2. **Implement Your API Endpoint**: - Create an API that accepts the parameters defined in your schema - Return the response in a structured format as shown above - Ensure your API handles errors gracefully 3. **Test Your Tool**: - Use the VAPI testing interface to verify your tool works - Check that the response is properly structured and can be used in conversations ## Best Practices 1. **Keep Your Schema Simple**: - Define only the fields you need - Use clear descriptions for each parameter 2. **Structure Your Response for Conversation**: - Format dates and times in a natural language friendly way - Group related data for easier reference in conversations - Include summary information (total slots, date ranges, etc.) 3. **Error Handling**: - Provide meaningful error messages that can be communicated to users - Include fallback options when appropriate By following these guidelines, you'll be able to integrate your appointment slots API into VAPI conversations, allowing the AI to retrieve and discuss available appointment times with users effectively.