Actions
Custom action
Let your agent call your own API with the details it gathers in the chat, such as looking up an order or registering a return.
A Custom action lets your agent call your own HTTP endpoint mid-conversation. You tell it where to send the request and which details to collect, and the agent asks the customer for them, sends the request once it has everything required, and uses your endpoint's answer in its reply.
Use it for anything your own systems can do: check an order's status, register a return, look up a loyalty balance, or create a booking in a system OrbitBase doesn't connect to directly.
Before you start
- You need to be a workspace owner or admin.
- You need an endpoint that's reachable on the public internet, with an
http://orhttps://address. - Each custom action counts toward your plan's action limit. See Plans and limits.
Set up a custom action
Add the action
Go to Actions and click Add action. Choose Custom action and click Continue.
Name it and write the instructions
Give the action a Name, such as "Check order status". In Instructions (up to 500 characters), describe when your agent should use it and what to gather first. Be specific about when it should, and shouldn't, fire.
Enter the endpoint
Under Endpoint, enter the URL and choose the Method: GET, POST, PUT, PATCH or DELETE. POST is the default.
Add headers
Under Headers, click Add header for anything your endpoint needs on every request, such as an
Authorizationheader. Turn on Secret for anything sensitive. You can add up to 8 headers.Choose the details to collect
Under Details to collect, click Add detail for each piece of information the agent should ask for. Give each one a name, an Answer type, and decide whether it's Required.
Send a test request
Under Test, click Send test request to check your endpoint answers.
Choose what happens next
Under When it's done, choose whether your agent keeps chatting, closes the conversation, or hands it to your team after a successful call.
Create the action
Click Create action.
Headers and secrets
Headers are sent with every request. When you mark a header as Secret, its value is stored apart from the action's other settings and is never sent back to your browser. After you save, the value box shows Leave blank to keep the saved value: leave it empty to keep what's stored, or type a new value to replace it.
Always mark API keys, tokens and passwords as Secret. Non-secret header values are visible to anyone who can edit the action.
Sign requests
Turn on Sign requests to add a signature header to every call, so your endpoint can check that the request came from OrbitBase and not from someone who learned the URL. The action gets its signing key when you create it, and keeps the same key across later edits.
How details are sent
Each detail is sent under a key made from its name in lower case, with spaces and symbols replaced by underscores. For example, a detail called Order number is sent as order_number.
- GET and DELETE send the details as query parameters on the URL.
- POST, PUT and PATCH send them as a JSON body.
Answer types
| Answer type | What the agent collects |
|---|---|
| Text | Anything the customer types. |
| Something that looks like an email address. | |
| Phone | A phone number, with a country code if they give one. |
| Number | Digits only, such as quantities, order numbers or amounts. |
| Link | A full web address, including https://. |
| Date | A real calendar date, not "next Tuesday". |
| Choices | One answer from a fixed list you set, shown as buttons. Up to 8 choices. |
An action can collect up to 12 details. Required details block the call until the customer answers them.
Turn on Ask with a form to show every detail at once as a form the customer fills in and submits. This works on your website widget and in the Playground. Social channels have no forms, so the agent keeps asking one question at a time there.
Testing your endpoint
Send test request sends a real request to your endpoint with sample values, exactly as your agent would. Nothing is saved and no customer sees it. You'll see the status your endpoint answered with, how long it took, and its response.
The test sends a value for every detail you collect, so an endpoint that creates records will create one. Use a test endpoint or clean up afterwards.
- If you've turned on Sign requests and haven't created the action yet, the test is signed with a temporary key. Your endpoint gets its real signing key once you create the action.
- If you change the endpoint to a different address, your saved secret values aren't sent with the test. Re-enter them to test against the new address.
What your agent does with the response
- Your endpoint has 10 seconds to answer. After that, the request is treated as timed out.
- The agent reads your endpoint's status and the first 2,000 characters of its response, and uses them to tell the customer the outcome. Return a short, clear response, such as plain text or a small JSON object, for the best replies.
- If the request fails, the agent apologises and offers to pass the request to a teammate rather than retrying endlessly.
- For POST, PUT, PATCH and DELETE, the same request runs at most once per conversation, so a retried message can't, for example, place an order twice. GET requests run every time, so lookups stay fresh.
After three failed calls in a row, the action's card shows Failing, with the last error and when it last worked.
Troubleshooting
The test fails
Check that the URL is correct and publicly reachable, that the method matches what your endpoint expects, and that any required headers are set. The response panel shows what your endpoint sent back.
The agent never uses the action
Check the action is switched on, and make the Instructions more specific about the situations it's for. Try it in the Playground.
The agent says it couldn't complete the request
Look at the action's card on the Actions page. If it shows Failing, the last error explains what went wrong, such as a status code or a timeout.