Developer Guide · Guides

Remote actions

Register endpoints of your platform with Inboxi so your team can run them from the dashboard and the inbox, and so the AI agent can fetch live data when it needs it.

A remote action is a named HTTP call into your system: activate subscription, resend invoice,get exam results. Your platform registers it once through the API. From then on Inboxi users can execute it with a click, and Inboxi makes the request to your callbackUrl and records the result.

How it works

POST /api/v1/actions

once

Inboxi

Listed under Remote Actions

dashboard

Agent clicks Execute

Fills parameters, confirms

HTTP call

Your callbackUrl

Receives the request, replies

Register an action

POST/api/v1/actionsCreate or update an action by name (permission: write)

Parameter	Type	Required	Description
`name`	string	required	Machine name, unique in your workspace, e.g. activate_subscription. Registering the same name again updates the action.
`callbackUrl`	string	required	The URL Inboxi calls. May contain {placeholders} filled from parameters, e.g. https://api.example.com/students/{phone}/results.
`label`	string	optional	Display name in the dashboard. Defaults to name.
`description`	string	optional	What the action does. Also shown to the AI agent for lookups.
`method`	string	optional	GET, POST (default), PUT, PATCH or DELETE.
`category`	string	optional	Groups actions in the dashboard. Defaults to general.
`headers`	object	optional	Extra headers sent on every call, e.g. your own Authorization token.
`parameterSchema`	array	optional	Input fields: [{ name, type, label, required }]. The dashboard renders a form from it.
`requiresConfirmation`	boolean	optional	Ask the user to confirm before executing. Default true.

curl -X POST https://inboxi.app/api/v1/actions \
  -H "X-API-Key: $INBOXI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "activate_subscription",
    "label": "Activate subscription",
    "description": "Activate a student subscription on the academy",
    "callbackUrl": "https://api.example.com/inboxi/actions/activate",
    "category": "subscriptions",
    "headers": { "Authorization": "Bearer YOUR_PLATFORM_TOKEN" },
    "parameterSchema": [
      { "name": "subscriptionId", "type": "string", "label": "Subscription ID", "required": true },
      { "name": "plan", "type": "string", "label": "Plan" }
    ]
  }'

Registration is idempotent, so it is safe to run it on every deploy of your platform. List, update and delete actions with GET, PUT and DELETE on /api/v1/actions; see the API reference.

The callback request

When an action is executed, Inboxi sends:

http

POST https://api.example.com/inboxi/actions/activate
Content-Type: application/json
X-Inboxi-Action: activate_subscription
X-Inboxi-Organization: <your workspace id>
Authorization: Bearer YOUR_PLATFORM_TOKEN      <- from the action's headers

{
  "subscriptionId": "enrollment_3341",
  "plan": "premium"
}

Body: for POST, PUT and PATCH, the parameters as JSON. For GET, parameters go in the query string instead. DELETE has no body.
Placeholders: {name} in the URL is replaced by the URL-encoded parameter of that name, and that parameter is not repeated in the query string.
From the inbox: when executed from a conversation, Inboxi adds the contact's phone in several formats: contactIdentifier, phone, mobile, phoneIntl and phoneRaw, so your endpoint can match the customer whichever format it stores.

What your endpoint should do

Rule	Detail
Authenticate the call	Check the secret header you registered in `headers`. Inboxi does not sign action callbacks, so this header is your proof the call is genuine.
Respond within 15 seconds	Longer calls are aborted and logged as failed.
Return 2xx on success	Optionally with JSON such as `{ "message": "Subscription activated" }`; it is stored and shown to the user.
Return 4xx/5xx on failure	The status and body are logged; the user sees the action failed.
Be idempotent	A user may click twice. Activating an already-active subscription should succeed quietly.

How actions appear in Inboxi

Registered actions are listed in Settings › Developer Hub › Remote Actions, grouped by category. Each has an Execute button that opens a form built from parameterSchema (or a JSON editor), aConfirm & Execute step, and an expandable list of Recent Executions with status, HTTP code and duration. Executing requires the automation permission on the user's role.

Remote Actions before any action is registered. Registered actions appear here grouped by category.
1Remote Actions tab.
2Empty state until your platform calls POST /api/v1/actions.
3An example registration request.

Live lookups for the AI agent

Some data is too big or changes too often to push as external data: a question bank, live exam results, stock levels. Register it as a GET action and the AI agent can call it when a question needs it.

Register a GET action with a clear description and a parameterSchema, for example get_exam_results with a phone parameter and callback https://api.example.com/students/{phone}/results.
Mention the action's name in the AI agent's instructions (for example “use get_exam_results when a student asks for their marks”). Only actions named in an agent's instructions are offered to that agent.
When needed, the agent asks for the lookup, Inboxi calls your endpoint, and the agent answers with the result. Responses are truncated to about 6,000 characters, so return only what is useful.

Only GET actions are offered to the AI agent, so it can read but never change data in your system. Actions that change data stay human-triggered.