Call Webhook

The Call Webhook tool empowers your AI agent to interact with external HTTP REST APIs, enabling it to perform a wide range of actions beyond its default capabilities. By configuring this tool, you can integrate your agent with other systems, automate tasks, and enhance conversations with real-time data. This guide will walk you through the configuration and usage of the Call Webhook tool, complete with examples to illustrate its functionality.

Overview

The Call Webhook tool allows your AI agent to:

• Send Data to External APIs: Collect information during a conversation and send it to an external system.
• Receive and Utilize API Responses: Use data returned from the API call to inform or enhance the ongoing conversation.
• Automate Workflows: Trigger actions in other systems, such as creating support tickets, updating records, or retrieving information.

Configuration Parameters

To set up the Call Webhook tool, you'll need to configure several parameters:

1. Description: A brief explanation of what the tool does. This helps you reference the tool in your instructions.

   Example: "Submit Ticket"

2. URL: The endpoint URL of the API you want to call.

   Example: "https://api.example.com/tickets"

3. Method: The HTTP method to use for the request (e.g., GET, POST, PUT, DELETE).

   Example: "POST"

4. Headers: Any custom headers required by the API, such as authentication tokens or content types.

   Example:

   {
         "Authorization": "Bearer your_api_token",
         "Content-Type": "application/json"
       }

5. Query String Parameters: Parameters to include in the URL's query string. You can use variables collected from the conversation.

   Example: "?email=$email&status=open"

6. Body: The request body for POST or PUT requests, formatted as valid JSON. Variables from the conversation can be inserted here.

   {
         "name": "$name",
         "email": "$email",
         "message": "$additional_info"
       }

7. Response Identifiers: Specify keys from the JSON response that the agent can access, using dot notation. This limits the data the agent can use in the conversation.

   Example: "ticket_id", "status", "assigned_to.name"

How to Use the Call Webhook Tool

Step 1: Define the Purpose

Determine what you want the AI agent to achieve by calling the webhook. This could be anything from creating a support ticket, fetching account information, to scheduling an appointment.

Example Scenario: When a customer wants to submit a support ticket.

Step 2: Write Clear Instructions

Instruct your AI agent on how to interact with the caller and when to use the Call Webhook tool.

Instruction Example:

"Collect the caller's name, email, and a description of their issue. Then, use the 'Submit Ticket' tool with variables $name, $email, and $issue_description. Once the ticket is created, inform the caller of their ticket ID."

This tells the agent to:

1. Collect Information: Gather necessary details from the caller.

2. Call the Webhook: Use the tool to send data to the external API.

3. Utilize the Response: Extract specific information from the API response to continue the conversation.

Step 3: Configure the Call Webhook Tool

Using the configuration parameters, set up the tool as per your requirements.

Example Configuration:

• Description: "Submit Ticket"
• URL: "https://api.example.com/tickets"
• Method: "POST"
• Headers:

  {
        "Authorization": "Bearer abc123token",
        "Content-Type": "application/json"
      }

• Query String Parameters: (Leave blank if not needed)
• Body:

  {
        "customer_name": "$name",
        "customer_email": "$email",
        "issue": "$issue_description"
      }

• Response Identifiers: "ticket_id"

Step 4: Implement Variables in Instructions

Use variables to capture data from the conversation. Variables are denoted by a dollar sign ($) followed by the variable name.

Variable Examples:

• $name: The caller's name.
• $email: The caller's email address.
• $issue_description: Details of the caller's issue.

Step 5: Utilize API Responses in the Conversation

Specify how the agent should use the data returned from the API call.

Example:

• After receiving the ticket_id from the API response, the agent can say:

  "Thank you, $name. Your support ticket has been created. Your ticket ID is $ticket_id. Our team will reach out to you shortly."

Examples

Example 1: Checking Order Status

Scenario: A customer wants to check the status of their order.

Instructions:

1. Ask for the customer's order number.
2. Use the "Check Order Status" tool with variable $order_number.
3. Inform the customer of their order status using the response from the API.

Configuration:

• Description: "Check Order Status"
• URL: "https://api.example.com/orders/status"
• Method: "GET"
• Headers:

  {
        "Authorization": "Bearer your_api_token"
      }

• Query String Parameters: "?order_number=$order_number"
• Response Identifiers: "status", "estimated_delivery"

Agent's Dialogue:

• Agent: "May I have your order number to check the status?"
• Customer: "It's 12345."
• Agent: (Calls the webhook and receives the response)
• Agent: "Your order is currently '$status' and is expected to be delivered on $estimated_delivery."

Example 2: Scheduling an Appointment

Scenario: A client wants to schedule an appointment.

Instructions:

1. Collect the client's name, preferred date, and service required.
2. Use the "Schedule Appointment" tool with variables $name, $date, and $service.
3. Confirm the appointment details with the client.

Configuration:

• Description: "Schedule Appointment"
• URL: "https://api.example.com/appointments"
• Method: "POST"
• Headers:

  {
        "Authorization": "Bearer your_api_token",
        "Content-Type": "application/json"
      }

• Body:

  {
        "client_name": "$name",
        "appointment_date": "$date",
        "service_type": "$service"
      }

• Response Identifiers: "confirmation_number", "scheduled_time"

Agent's Dialogue:

• Agent: "Could you please provide your name?"
• Customer: "Alex Johnson."
• Agent: "What date would you like to schedule the appointment?"
• Customer: "Next Monday."
• Agent: "Which service are you interested in?"
• Customer: "Haircut."
• Agent: (Calls the webhook and receives the response)
• Agent: "Your appointment is confirmed for $scheduled_time on $date. Your confirmation number is $confirmation_number."

Response Identifiers and Dot Notation

When the API returns a JSON response, you can specify which parts of the response the agent can access using response identifiers.

Example Response:

{
  "ticket": {
    "id": "TICKET123",
    "status": "open",
    "assigned_to": {
      "name": "Support Agent",
      "email": "[email protected]"
    }
  },
  "message": "Ticket created successfully."
}

Response Identifiers:

• "ticket.id": Accesses the ticket ID.
• "ticket.status": Accesses the status of the ticket.
• "ticket.assigned_to.name": Accesses the name of the assigned support agent.

By specifying these identifiers, you control what information the agent can use, enhancing security and relevance.

Best Practices

• Ensure Valid JSON: The body of POST or PUT requests must be valid JSON. Double-check for syntax errors.

• Secure Data Transmission: Use HTTPS URLs and include necessary authentication headers to protect data.

• Variable Naming: Use clear and consistent variable names that match the data being collected.

• Error Handling: Instruct the agent on what to do if the API call fails or returns an error.

  Example Instruction:

  "If the 'Submit Ticket' tool fails, apologize to the caller and inform them that we will follow up via email."

• Testing: Before deploying, test the webhook calls to ensure they work as expected and the agent handles the responses correctly.

Advanced Usage

Using Dynamic Query Strings

You can include variables in the query string to pass data via the URL. Your agent already knows a lot of information from the conversation, things like current date and time, caller's caller ID information (if available), callers phone number (if on a phone call) and more. You can use all this information by instructing the agent as well.

Example 1:

• URL: "https://api.example.com/findCustomer"
• Query String Parameters: "?phoneNumber=$phone_number&limit=10"
• Instructions: "When the caller wants to know their account balance, find the customer using variables $phone_number"

Example 2:

• URL: "https://api.example.com/search"
• Query String Parameters: "?query=$search_term&limit=10"

Customizing Headers

Include custom headers for APIs that require them, such as:

• "X-Custom-Header": "CustomValue"

Handling Different HTTP Methods

• GET: Retrieve data without a body.
• POST: Send data to create a new resource.
• PUT: Update an existing resource.
• DELETE: Remove a resource.

Ensure the method matches the API's requirements.

Utilizing API Responses to Enhance Conversations

Use the data returned from the API to make the conversation more informative.

Example:

• Scenario: Providing real-time stock levels.

• Agent: "Let me check the availability of that item."

• Agent: (Calls the webhook and retrieves the stock level)

• Agent: "We currently have $stock_quantity units available."

Summary

The Call Webhook tool extends your AI agent's functionality by enabling it to interact with external APIs. By carefully configuring the tool and writing clear instructions, you can automate tasks, provide real-time information, and create a more engaging and efficient experience for your customers.

Remember to:

• Define clear purposes and instructions for the agent.
• Use variables to capture and pass data effectively.
• Securely configure API calls with the correct methods, headers, and body content.
• Utilize response identifiers to control the data the agent accesses.
• Test thoroughly to ensure seamless operation.

By mastering the Call Webhook tool, you unlock a powerful mechanism to integrate your AI agent with the broader digital ecosystem, enhancing both your operations and customer interactions.

You can visit the Tool Usage guide for a brief overview of all the tools.