Custom Actions let your receptionist connect to any third-party system through its API. Use them to look up info (like an order status or service area), add records (like a new CRM contact), or trigger any workflow that has an API endpoint.
Each action runs at one of three moments: When call starts, During call, or After call. Bearer token and OAuth authentication are both supported.
How to set up a Custom Action
1. Add the action and choose when it runs
Go to Agent > Custom actions and add a new action. Every action has an Action name and Instructions for the receptionist. The field labels are the same for all three triggers, but what you write in the instructions changes depending on when the action runs.
When call starts: the action runs the moment a call comes in. The only variable you can use in the request is the caller ID. Write instructions describing what to do with the info this action returns. Use this trigger when you want the receptionist to look up the caller in another system the moment the call connects, for example pulling their CRM record by phone number so the receptionist greets them by name and knows their history. Example action name: Find customer in CRM.
During call: the action runs when a scenario you describe in the instructions comes up. Write instructions telling the receptionist when to trigger this action and what to do with the response. Use this trigger when you want the receptionist to collect info from the caller (like an order number) and use it as a variable in the request mid-call. Example action name: Look up order status.
After call: the action runs automatically every time a call ends, so no instructions are needed. Use this trigger to push call summaries, transcripts, or caller info to other systems for follow-up. Example action name: Push call summary to CRM.
2. Set your variables
If your action runs during the call, set the variables the receptionist will collect from the caller during the conversation. Each variable becomes available to use in your API request.
For each one, add a name, description, and example.
Example:
Name:
order_numberDescription: The caller's 4-digit order number.
Example: 1234
The receptionist asks the caller for this info during the conversation, then drops it into the request using {{variable_name}} wherever you reference it.
Note: if you are running your action "when the call starts" the only available variable is caller_id. If you are running it after the call, you have access to the following:
{{call_id}}
{{caller_id}}
{{agent_name}}
{{receptionist_name}}
{{receptionist_phone_number}}
{{start_date_time}}
{{end_date_time}}
{{duration_seconds}}
{{transcript}}
{{call_summary}}
3. Configure the request
This is where you tell Upfirst what request to make to your API. Work through each section in order.
Set the method and endpoint URL
Choose the method (GET, POST, PUT, PATCH, DELETE) and enter the endpoint URL from the API you're connecting to.
You can insert variables anywhere in the URL using {{variable_name}}. For example, to look up the caller by phone number at the start of a call, your URL might be:
Choose your authentication
Custom Actions support three authentication methods:
None: use if your API doesn't require auth (rare for production APIs).
Bearer token: paste your API key (or bearer token) into the box. Upfirst will send it as an
Authorization: Bearer <your token>header automatically.OAuth: select a saved OAuth Connection. If you haven't set one up yet, follow How to set up an OAuth Connection for Custom Actions first.
Add headers (if needed)
Click Add header and enter the header name and value. Most APIs need a Content-Type header (typically application/json) for POST, PUT, or PATCH requests. Check your provider's docs for any other required headers.
Add query parameters (if needed)
Click Add query and enter the key and value. Query parameters get appended to the URL after a ? (e.g., ?status=active). You can use {{variable_name}} in query values.
Add the request body
The body is the last step in the request configuration. For POST, PUT, and PATCH requests, this is where you send data to the API.
For "When call starts" actions, this is also where you typically reference {{caller_id}} to look up the caller in your other system.
Use {{variable_name}} to insert variables anywhere in the body. Example body for looking up a customer by phone number:
{ "filter": { "property": "phone", "equals": "{{caller_id}}" } }
4. Test the action
Set a timeout in seconds for how long your receptionist should wait for a response.
Edit the fallback message the receptionist will say if the action fails or times out.
Add sample values for your variables, review the request preview, and click Run test to see the live response.
5. Pick the response fields
Most API responses include more info than the receptionist needs. Select only the fields the receptionist should have access to on the call. Then save.
The fewer fields you expose, the less likely your receptionist is to get confused or read out something it shouldn't.
Variables available by trigger
Trigger | Available variables |
When call starts |
|
During call |
|
After call |
|
Common uses
Use case | Trigger | What it does |
Find an order status | During call | Receptionist asks for the order number, calls your order API, and reads the status back to the caller |
Look up a customer | When call starts | Pulls the caller's account by phone number before the conversation begins |
Check service area | During call | Confirms a zip code is covered before booking |
Push call summary to CRM | After call | Sends the caller's info and call summary to your CRM |
Things to know
Bearer token and OAuth are both supported for authentication. For OAuth, set up the connection first. See How to set up an OAuth Connection for Custom Actions.
Only expose the response fields the receptionist actually needs. Extra fields can lead to confused answers.
Test every action with sample values before saving.
"When call starts" actions can only use the caller ID (no other variables).
The instruction text the receptionist sees changes based on the trigger you pick. Make sure your instructions match the moment the action runs.
Set a sensible timeout. The receptionist will fall back to your fallback message if the API doesn't respond in time.