Add custom actions to your assistant

A custom action lets your assistant call a web address during a conversation. For example, it can look up an order's status, check stock, or send a new lead to your own system. You give AIVA a URL, an HTTP method and the inputs the AI should collect. You don't write any code. You need an assistant and a URL your tool or service provides. Custom actions are set per assistant.

1. Open the assistant's actions

1. In the sidebar, open AI Configuration → Assistants.
2. Click the assistant's row, or its Edit button.
3. Open the Actions tab.
4. Switch to Custom actions.

2. Add a custom action

1. Click Add custom action.
2. Fill in the form:
   • Name (letters, numbers, underscores): a short name such as look_up_order_status. Start with a lowercase letter and use only lowercase letters, numbers and underscores. It can't match one of AIVA's built-in action names.
   • Description (tells the AI when to use it): say plainly what the action does and when to use it, for example "Look up an order's shipping status by its order id". The AI decides when to call the action based on this text, so be specific.
   • The HTTP method: pick GET, POST, PUT, PATCH or DELETE from the list next to the URL field.
   • URL: the full address, starting with http:// or https://.
3. Under Inputs the AI fills in, click Add input for each piece of information the AI should collect from the caller. For each input, enter:
   • Name: starts with a letter, then letters, numbers or underscores (for example order_id).
   • Description: what the value is, so the AI asks for the right thing.
   • The type, from the list next to it: Text, Number or True/false.
4. Click Save.

The action is saved straight away and appears in the list with its method and URL.

3. What AIVA sends

When the AI uses the action, AIVA calls your URL with the values it collected:

Method	Where the inputs go
GET, DELETE	Added to the URL as query parameters
POST, PUT, PATCH	Sent as a JSON body

The form has no field for request headers, so your endpoint can't rely on a header for login details. Many automation tools give you a unique URL that works on its own.

Your endpoint should answer quickly and keep its reply short. The AI reads the response and uses it in the conversation. Very long responses are cut off. Card numbers and other sensitive details in the response are scrubbed before the AI sees them, and the AI treats the response as information, never as instructions.

4. When the AI uses it

Your assistant can use custom actions on phone calls and in website chat. It calls one when the conversation matches the action's description and it has the inputs it needs. If an input is missing, it asks the caller for it first.

If your endpoint answers with an error, or can't be reached, the action counts as failed. The AI tells the caller it couldn't do that, and offers to have someone follow up. You can check what happened afterwards: open the call under Communication → Calls → Logs and look at Actions taken, where each action shows Done or Failed.

To try an action before real callers do, use the assistant's Test tab and ask something that should trigger it.

5. Approval for custom actions

Custom actions you add in the dashboard run automatically, with no approval step. The form has no approval setting. If you don't want the AI to call one any more, delete it.

Built-in actions, such as sending a follow-up text, are different. On the Actions tab you can set each one to Automatic, Ask first or Never, or switch it off. See Approvals and autonomy.

6. Delete a custom action

On the Custom actions tab, click the bin icon next to the action. Confirm with Delete action in the Delete custom action window. The assistant can no longer call it in any conversation.

Troubleshooting

• Fill in the name, description, and URL.: all three fields are required.
• Give the action a lowercase name using only letters, numbers, and underscores (e.g. look_up_order_status).: remove capital letters, spaces and symbols from Name.
• "…" is already a built-in action name -- choose a different one.: pick another name.
• Enter a full URL starting with http:// or https://.: include the https:// part.
• Each input needs a name starting with a letter (letters, numbers, and underscores only).: fix the input's Name.
• The action always fails: AIVA won't call private or internal network addresses, and it doesn't follow too many redirects. Use the public address of your service, and check that it accepts the method you picked.

Next steps

• Set approvals and autonomy for the built-in actions.
• Send AIVA events with webhooks and Zapier to push call results to your tools after the conversation.
• Test your assistant before you publish changes.