Custom Actions

Custom actions are HTTP requests your agent can run before or during a call. Use them when you need live data from an external API or when the agent must trigger a workflow outside Synthflow, such as creating CRM records, checking an order status, or sending structured data to another system.

Create and configure a custom action

Open Actions, create a Custom Action, then configure four parts:

1. Request setup: select method, endpoint URL, headers, body, and authentication.
2. Variables: define fields the model should extract or inject.
3. Action details: set a clear name and description so the model knows when to call it.
4. Result handling: write prompt logic that uses returned data in the next turn.

Use the request method that matches the API operation you want to run:

Variables

Use variables to map conversation context into requests:

• User-defined variables for values you want extracted during the call, such as full_name or order_id.
• Default variables for call metadata, such as call_id, twilio_call_sid, to_phone_number, from_phone_number, and user_phone_number.

1
{
2
  "phoneNumber": "<user_phone_number>",
3
  "fullName": "<full_name>",
4
  "callId": "<call_id>"
5
}

Authentication

Choose the authentication mode your endpoint expects in the Authentication Type menu. Available built-in connections include:

• Salesforce and Salesforce Sandbox
• HubSpot
• GoHighLevel

Match the action configuration to your provider’s required header format and environment.

Instructions

To configure what the agent says while an action runs, open Actions > your custom action > AI Instructions.

You can set:

• Start message
• Delay message
• Failure message

If you disable Let the agent speak naturally, the agent will follow your configured messages more strictly.

Initialize

After you finish configuration, variables, authentication, and message setup, click Initialize in the action editor before using the action in production flows.

Initialization validates that your endpoint, authentication, and payload are configured correctly. Without this step, your action is not ready for reliable use.

Once initialization succeeds, the returned fields become action result variables that you can reference later in prompts or pass into other actions.

Inspect requests

Every time your custom action runs during a call, the request and response are recorded in API logs. Open the matching entry to inspect the request URL, headers, body, response payload, and timing details for that specific call.

Examples

Retrieve date and time

You can create a lightweight GET custom action to fetch current local time before a call starts, then use that result in prompts.

Use http://worldtimeapi.org/api/timezone/:area/:location[/:region] and replace placeholders with your timezone, for example America/Chicago. For the full timezone list, call http://worldtimeapi.org/api/timezone.

Run several custom actions

You can chain actions so one response feeds the next step.

For example, you can run one action to fetch a customer email from your CRM and a second action to use that email for booking or an update. Attach both actions to the same call flow stage (typically During Call) and describe execution order in your prompt logic so the model runs the first action before passing the returned fields to the second.

FAQ