Actions

About custom actions

What are custom actions?

Custom actions in Synthflow AI allow you to extend your Assistant’s capabilities by integrating external APIs.

Whether pulling in live information, creating new records, or adjusting conversational flow based on external inputs, custom actions make your Assistant more capable.

What can custom actions do?

  • Connect to APIs

Make GET or POST requests to fetch or send data.

  • Use dynamic variables

Insert user-specific data before or during the call.

  • Automate workflows

Create, update, or retrieve external data automatically.

  • Make conversations better

Use API responses to generate context-aware AI interactions.

GET vs. POST requests in custom actions

Custom actions can be configured with different HTTP methods based on the type of request:

  • GET requests

Use GET requests to retrieve data from an API. The Assistant can pull in information, such as user details or order statuses, based on provided identifiers.

  • POST requests

Use POST requests to create new resources. This could include logging call details, adding a new user to a database, or scheduling an appointment. POST requests require a structured output schema to organize the information the Assistant sends.

How custom actions work

1.** Define the API call.**

Choose the method (GET or POST), add the API endpoint, and configure authentication if required.

2. Set up variables.

Create placeholders for user data, define descriptions to guide the AI, and specify data types.

3. Configure structured output (for POST requests).

Ensure the Assistant sends correctly formatted data to the API.

4. Use the API response in conversations.

Write prompts to guide how the Assistant proceeds with the data.

Why use custom actions?

Synthflow AI’s custom actions let your Assistant pull in real-time data, trigger external actions, and automate tasks, so it can do more without extra manual work.

By integrating with other services, it can adjust responses based on API results, making interactions feel more natural and personalized. This keeps workflows running smoothly and helps your Assistant stay useful and relevant.

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).
> 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: **

VariableDescriptionType
first_nameUser’s first namestring
last_nameUser’s last namestring
user_emailUser’s emailstring
signup_dateCurrent datedatetime


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: **

VariableDescriptionType
order_idThe order’s unique identifierstring
statusNew status for the orderstring

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

1{
2    "id": "<call_id>",
3    "user_phone": "<user_phone_number>",
4    "inbound": "<to_phone_number>",
5    "outbound": "<from_phone_number>",
6    "twilio_id": "<twilio_call_sid>"
7}