In-depth Custom Actions Details

1. Introduction

Custom Actions in Synthflow AI are HTTP requests (GET, POST, PUT, etc.) that your Assistant can trigger at different stages of a call or conversation. These requests can fetch or send data to external APIs, allowing you to:

• Integrate live data (e.g., retrieve a user’s order status).
• Automate workflows (e.g., create or update CRM records).

💡

Tip: Use Custom Actions to enrich conversations with live, dynamic data—making your Assistant feel more intelligent and responsive.

This guide expands on the basics to show you how to work with multiple HTTP methods, authenticate with external APIs, and leverage variables—both user-defined and automatically provided by Synthflow.

2. Supported HTTP Methods

Synthflow AI Custom Actions currently support the main HTTP methods: GET, POST, PUT, PATCH, and DELETE. Below are typical use cases and examples.

2.1 GET Requests

Use GET requests to retrieve information during a call. For example:

• Fetch a user profile before the call begins.
• Look up the status of an order in real time.
• Check the state of a subscription.

Most often, variables sent via parameters for this type of API call are:

• user_phone_number
• call_id
• to_phone_number
• from_phone_number
• twilio_call_sid

2.2 POST Requests

POST requests are ideal for creating new records or triggering actions that change server state. Use POST to:

• Create a new user account or lead.
• Submit form data or feedback.
• Book an appointment.

Example JSON Body for POST (Creating a New User):

{
  "first_name": "<first_name>",
  "last_name": "<last_name>",
  "email": "<user_email>",
  "signup_date": "<signup_date>"
}

Variables used:

2.3 PUT Requests

PUT requests are used to update or replace existing resources. Use PUT to:

• Update existing user profiles
• Modify order statuses or shipping details.

Example for Updating an Order Status

{
  "order_id": "<order_id>",
  "status": "<order_status>"
}

Variables used:

3. Authentication

Depending on your API’s requirements, you can set up different authentication methods for your Custom Action. Synthflow AI currently supports:

1. No Authentication
2. Basic Authentication
3. Bearer/Token Authentication
4. OAuth2 Authentication for Hubspot and GoHighLevel

❗️

Synthflow doesn't support custom OAuth out of the box.

3.1 No Authentication

If your API endpoint is publicly accessible or does not require credentials, you can leave authentication turned off.

3.2 Basic Authentication

Basic Authentication requires encoding the username:password pair in Base64 and passing it in the Authorization header.

Format:

Authorization: Basic <base64(username:password)>

💡 You can use online tools like DebugBear or ChatGPT to generate this string from your username and password.

3.3 Token-Based Authentication

Some APIs require a token in the header.

Typically you will have "Authorization" as your authentication Key and "Bearer something" as your authentication value. For example, when connecting to OpenAI API, your authentication header will look like:

Authorization: Bearer sk_test_51NRxS5JG...

In this case, you set your values as follows:

Some APIs may use Token instead of Bearer. Always check the API docs.

4. Variables

Variables in Synthflow AI are placeholders that capture dynamic data during a call, allowing you to map user input and system-generated information to your API requests. There are two main categories of variables:

4.1 User-Defined Variables

These variables are explicitly created in your Assistant configuration. They capture specific details provided by the user during the call. For example:

• {lead_name}: The user's name.
• {user_email}: The user's email address.
• {order_id}: An order identifier supplied during the call.

📘

Ensure the Assistant’s prompt explicitly asks for the variables so that they can be reliably captured during the conversation.

How They Are Collected:

• Before the Call: These variables, most of the time, act as unique identifiers for fetching some call context.
• During the Call: The AI extracts the variable from the conversation transcript based on the prompt and variable description. To improve accuracy, use a detailed description and clearly define expected data type.

4.2 Special Default Variables

Synthflow AI automatically provides these default variables for every call, so you don’t need to define them manually. They are particularly useful for maintaining context within your API calls.

Call Context

• call_id: A unique identifier for each call session.
• twilio_call_sid: The unique identifier provided by Twilio (if using Twilio for telephony).

Phone Numbers

• to_phone_number: For inbound calls, the number you own that was dialed.
• from_phone_number: For outbound calls, the number your Assistant used to call the user.
• user_phone_number: For inbound calls, this is the caller’s number. For outbound calls, this is the number of the recipient.

Example Usage

{
    "id": "<call_id>",
    "user_phone": "<user_phone_number>",
    "inbound": "<to_phone_number>",
    "outbound": "<from_phone_number>",
    "twilio_id": "<twilio_call_sid>"
}