Actions

An action lets an expert call one of your own systems while it answers, so it can do more than read documents. For example, it can look up an order status by order number. You describe the web address to call, and the expert decides from the question whether to call it.

Actions are on the Professional plan. Setting one up involves a web address and a small piece of JSON, so you will probably want someone technical beside you the first time.

Before you start

You need a web address that your system answers on, and you need to know what it expects to be sent. The address has to follow these rules.

It must start with https://.
It must use a hostname such as api.yourcompany.com, not a bare IP address.
It must be reachable from the public internet. An address that only works inside your office network cannot be called.

Creating an action

In the sidebar open Experts, then Actions.
Select New action.
Fill in the form.
- Name. For example Look up an order.
- When to use it. One sentence telling the expert when to call this, for example "Look up an order's status by its order number." The expert reads this and nothing else to decide, so a vague sentence means it calls at the wrong time, or never.
- Method and URL. Choose GET or POST, then paste the address. Anything in braces, such as {order_no}, is filled in by the expert from the inputs below. So https://api.yourcompany.com/orders/{order_no} needs an input called order_no. Only the path and the query can contain braces, not the hostname.
- Inputs (JSON Schema, optional). What the expert has to work out before it can call. Leave it blank if the call takes nothing. An example:
```
{"type":"object","properties":{"order_no":{"type":"string","description":"The order number"}},"required":["order_no"]}
```
- Auth. None, Bearer token or Custom header. For a custom header, also fill in Header name, for example X-Api-Key.
- Credential. Paste the key or token. It is stored encrypted and is never shown again. It is sent to your address on each call and nowhere else. When you edit an action that already has one, leave the box empty to keep it, or paste a new one to replace it.
- Give up after. 3 seconds, 8 seconds or 15 seconds. Someone is waiting for the answer, so a slow system is better abandoned than waited for.
Select Create action.

Aimy checks the form when you save. It tells you if the address is not https, does not resolve, points at a private address, or has a brace name that is missing from the inputs, and if the inputs are not valid JSON.

Letting an expert use it

Creating an action does not give it to anyone. Open Configure, choose the expert, go to Actions, tick the ones it may call and select Save changes. Each tick shows the method and the host, so you can see which of your systems the expert reaches. One expert can have up to five actions.

Managing the list

The list shows each action with the method and host it calls, how many experts use it, whether it is on or off, who added it and when. A small key label means a credential is stored. The filters work like the ones on the Instructions page: by expert, by On and Off, and by search. If you call more than one system, a Calls list also filters by host.

Edit opens the form again.
Turn off stops every expert using it. Turn on brings it back.
Delete removes it, and asks you to confirm.

Things to keep in mind

Only give an expert actions that are safe to run whenever someone asks a matching question.
Prefer GET for looking things up. Use POST only where the call really needs to send something.
Keep the inputs small. Each action has a size limit, and an expert's actions together have one too.

If your plan does not include them

On Business the Actions row in the sidebar is dimmed and marked as a Professional feature. If you move from Professional to Business, what you set up is kept, including the stored credentials, but no expert calls it. The page stays open so you can read or remove it. Upgrading brings it all back. See Plans.